Troubleshooting

Overlay Documentation

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

This page covers common issues and solutions for overlay E2E tests.

Setup Issues

"Node.js version X required"

Problem: Package requires Node.js 22+.

Solution:

# Check version
node --version

# Use nvm to install/switch
nvm install 22
nvm use 22

"yarn: command not found"

Problem: Yarn is not installed.

Solution:

# Enable corepack (includes yarn)
corepack enable

# Or install yarn
npm install -g yarn

"Cannot find module 'rhdh-e2e-test-utils'"

Problem: Dependencies not installed.

Solution:

yarn install

"Executable doesn't exist" (Playwright browsers)

Problem: Playwright browsers not installed.

Solution:

npx playwright install
# Or with system dependencies
npx playwright install --with-deps

Cluster Connection Issues

"oc: command not found"

Problem: OpenShift CLI not installed.

Solution: Download from OpenShift CLI downloads.

"error: You must be logged in"

Problem: Not authenticated to cluster.

Solution:

oc login <cluster-url>
# Or
oc login --token=<token> --server=<server>

"Unable to connect to the server"

Problem: Cluster unreachable.

Solutions:

• Check VPN connection
• Verify cluster URL is correct
• Check if cluster is running

Deployment Issues

"Namespace not found"

Problem: Test namespace doesn't exist or was deleted.

Solution: The namespace is created automatically. If it's missing, re-run the tests.

"Deployment timeout"

Problem: RHDH deployment takes too long.

Solutions:

• Check cluster resources
• Check deployment logs:

  oc logs -f deployment/rhdh -n <namespace>

• Increase timeout in setup:

  test.beforeAll(async ({ rhdh }) => {
    test.setTimeout(10 * 60 * 1000);
    await rhdh.configure({ auth: "keycloak" });
    await rhdh.deploy();
  });

"ImagePullBackOff"

Problem: Cannot pull container images.

Solutions:

• Check image pull secrets
• Verify registry access
• Check image name/tag

"Keycloak deployment failed"

Problem: Keycloak fails to deploy.

Solutions:

• Check Keycloak namespace for errors:

  oc get pods -n rhdh-keycloak
  oc logs -f deployment/keycloak -n rhdh-keycloak

• If using guest auth and don't need Keycloak:

  SKIP_KEYCLOAK_DEPLOYMENT=true yarn test

• Check cluster resources (Keycloak requires memory/CPU)

Test Failures

"Element not found"

Problem: UI element not present.

Solutions:

• Add wait:

  await page.locator('text="Element"').waitFor({ state: "visible" });

• Check selector:

  await page.pause();  // Debug in browser

• Verify page loaded:

  await uiHelper.waitForLoad();

"Timeout waiting for selector"

Problem: Element takes too long to appear.

Solutions:

• Increase timeout:

  await page.locator('text="Slow"').waitFor({ timeout: 60000 });

• Check if element exists at all (use headed mode)

"Login failed"

Problem: Authentication fails.

Solutions:

• Check Keycloak is running
• Verify credentials (default: test1/test1@123)
• Check auth configuration

"Navigation failed"

Problem: Page navigation fails.

Solutions:

• Check baseURL is correct
• Wait for navigation:

  await page.waitForLoadState("networkidle");

Environment Variable Issues

"Variable undefined"

Problem: Environment variable not set.

Solutions:

• Check .env file exists and contains variable
• Verify dotenv is loaded:

  import dotenv from "dotenv";
  dotenv.config({ path: `${import.meta.dirname}/.env` });

• Set in test code:

  process.env.MY_VAR = "value";

"Variable not substituted in YAML"

Problem: ${VAR} appears literally in config.

Solutions:

• Set variable before rhdh.deploy()
• Check variable name matches exactly
• Verify envsubst is being applied

OpenShift CI Issues

OCI and Metadata Errors

"source.json not found" or "plugins-list.yaml not found"

• These files are required when GIT_PR_NUMBER is set.
• In CI they are generated automatically; for local runs, copy them from a CI job or create them manually.

"metadata directory not found" or "no valid metadata files"

• Ensure workspaces/<plugin>/metadata/ exists and contains valid Package CRD YAML files.
• If you intentionally want to skip metadata injection, set RHDH_SKIP_PLUGIN_METADATA_INJECTION=true.

"Tests pass locally but fail in CI"

Common causes:

• Missing Vault secrets
• Secrets not prefixed with VAULT_
• Missing Vault annotations
• Different cluster configuration

Solutions:

• Check CI logs for specific error
• Verify secrets in Vault have VAULT_ prefix
• Check Vault path has correct annotations:

  {
    "secretsync/target-name": "rhdh-plugin-export-overlays",
    "secretsync/target-namespace": "test-credentials"
  }

"Vault secret not available"

Problem: Environment variable from Vault is undefined.

Solutions:

• Verify secret name starts with VAULT_
• Check secret is in correct Vault path (global or workspace-specific)
• Verify Vault path has required annotations
• Request Vault access in team-rhdh channel if needed

"Resource quota exceeded"

Problem: Cluster limits reached.

Solutions:

• Clean up old namespaces
• Request quota increase
• Run fewer parallel tests

"Connection refused"

Problem: Service not accessible.

Solutions:

• Wait for service to be ready
• Check route/service configuration
• Verify network policies

Debugging Tips

Use Headed Mode

yarn test:headed

Use Playwright UI

yarn test:ui

Add Debug Pause

await page.pause();  // Pauses for manual inspection

Take Screenshots

await page.screenshot({ path: "debug.png" });

View Traces

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

Check Logs

page.on("console", msg => console.log(msg.text()));
page.on("pageerror", err => console.log(err));

Getting Help

If you're still stuck:

1. Check the Playwright documentation
2. Review rhdh-e2e-test-utils documentation
3. Check the overlay repository issues
4. Ask in the team chat

Related Pages

• Running Tests Locally - Local workflow
• CI/CD Pipeline - CI configuration
• Common Patterns - Best practices