Skip to content

docs: improve overlay docs and navigation #27

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
subhashkhileri merged 1 commit into from
Jan 30, 2026
Merged

docs: improve overlay docs and navigation #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion docs/.vitepress/config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -353,6 +353,10 @@ export default defineConfig({
text: "Pre-requisite Services",
link: "/overlay/tutorials/custom-deployment",
},
{
text: "Using Secrets",
link: "/overlay/tutorials/using-secrets",
},
{
text: "Running Tests Locally",
link: "/overlay/tutorials/running-locally",
Expand All @@ -376,12 +380,16 @@ export default defineConfig({
},
{
text: "Reference",
collapsed: true,
collapsed: false,
items: [
{
text: "Environment Variables",
link: "/overlay/reference/environment-variables",
},
{
text: "Local OCI Testing",
link: "/overlay/reference/local-oci-testing",
},
{
text: "Package.json Scripts",
link: "/overlay/reference/scripts",
Expand Down
42 changes: 42 additions & 0 deletions docs/guide/configuration/config-files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

RHDH deployment uses YAML configuration files for app config, plugins, and secrets.

If you are working inside the overlay repository, see [Overlay Configuration Files](/overlay/test-structure/configuration-files) for overlay-specific behavior and CI integration details.

## File Structure

Create configuration files in `tests/config/`:
Expand Down Expand Up @@ -137,6 +139,21 @@ When you deploy RHDH, configurations are merged:

Later files override earlier files. You only need to specify what's different from defaults.

## Verify the Final Merged Config

If you need to confirm the final merged configuration:

1. Run a test once so RHDH is deployed.
2. Inspect the ConfigMaps in the test namespace:

```bash
oc get configmap -n <namespace>
oc get configmap app-config-rhdh -n <namespace> -o yaml
oc get configmap dynamic-plugins -n <namespace> -o yaml
```

This shows the exact content after defaults, auth config, and your overrides are merged.

## Plugin Metadata Injection

During deployment, the package automatically handles plugin configurations from metadata files. The behavior depends on whether your [`dynamic-plugins.yaml`](#dynamic-plugins-yaml) file exists:
Expand Down Expand Up @@ -219,6 +236,31 @@ When `GIT_PR_NUMBER` is set (by OpenShift CI), local plugin paths are automatica

This allows E2E tests to run against the actual OCI images built for the PR.

### Local Reproduction (Optional)

If you want to reproduce OCI URL replacement locally, create the required files at the workspace root:

**source.json**
```json
{
"repo": "https://github.com/redhat-developer/rhdh-plugin-export-overlays",
"repo-ref": "abc123def4567890"
}
```

**plugins-list.yaml**
```yaml
plugins/tech-radar:
plugins/my-plugin:
```

Then set `GIT_PR_NUMBER` and run tests:

```bash
export GIT_PR_NUMBER=1845
yarn test
```

::: warning
For PR builds, OCI URL generation is required. Deployment will fail if `source.json` or `plugins-list.yaml` doesn't exist, or if version fetching fails.
:::
Expand Down
12 changes: 7 additions & 5 deletions docs/guide/configuration/environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,14 @@

Complete reference of all environment variables used by the package.

## Required Variables
## Recommended Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `RHDH_VERSION` | RHDH version to deploy | `"1.5"` |
| `INSTALLATION_METHOD` | Deployment method | `"helm"` or `"operator"` |
These are optional but commonly set to control deployment behavior:

| Variable | Description | Example | Default |
|----------|-------------|---------|---------|
| `RHDH_VERSION` | RHDH version to deploy | `"1.5"` | `"next"` |
| `INSTALLATION_METHOD` | Deployment method | `"helm"` or `"operator"` | `"helm"` |

## Auto-Generated Variables

Expand Down
32 changes: 12 additions & 20 deletions docs/guide/core-concepts/playwright-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,25 +25,28 @@ The `defineConfig` function extends your configuration with sensible defaults fo
|---------|-------|-------------|
| `testDir` | `./tests` | Test files location |
| `timeout` | 90,000ms | Test timeout |
| `expect.timeout` | 30,000ms | Assertion timeout |
| `expect.timeout` | 10,000ms | Assertion timeout |
| `retries` | 2 (CI), 0 (local) | Test retries |
| `workers` | 50% of CPUs | Parallel workers |
| `fullyParallel` | `true` | Parallel test execution |
| `outputDir` | `node_modules/.cache/e2e-test-results` | Playwright artifacts |

### Reporter Settings

| Setting | Value |
|---------|-------|
| `reporter` | `[["list"], ["html"]]` |
| `reporter` | `[["list"], ["html"], ["json"]]` |

### Browser Settings

| Setting | Value |
|---------|-------|
| `viewport` | `{ width: 1920, height: 1080 }` |
| `video` | `"on"` |
| `ignoreHTTPSErrors` | `true` |
| `trace` | `"retain-on-failure"` |
| `screenshot` | `"only-on-failure"` |
| `viewport` | `{ width: 1920, height: 1080 }` |
| `video` | `"on"` |
| `actionTimeout` | 10,000ms |
| `navigationTimeout` | 50,000ms |

## Global Setup

Expand All @@ -55,22 +58,12 @@ The base configuration includes a global setup that runs before all tests:

## Customizing Configuration

You can override any setting by passing it to `defineConfig`:
`defineConfig` only accepts `projects` overrides. To change other settings, use `baseConfig` with Playwright's `defineConfig`.

```typescript
import { defineConfig } from "rhdh-e2e-test-utils/playwright-config";

export default defineConfig({
// Override timeout
timeout: 120000,

// Override retries
retries: 3,

// Override workers
workers: 2,

// Add projects
projects: [
{
name: "my-plugin",
Expand All @@ -81,9 +74,6 @@ export default defineConfig({
testMatch: "**/another-*.spec.ts",
},
],

// Add custom reporter
reporter: [["list"], ["html"], ["json", { outputFile: "results.json" }]],
});
```

Expand Down Expand Up @@ -179,12 +169,14 @@ GITHUB_TOKEN=ghp_xxxxx
## Example: Full Configuration

```typescript
import { defineConfig } from "rhdh-e2e-test-utils/playwright-config";
import { baseConfig } from "rhdh-e2e-test-utils/playwright-config";
import { defineConfig } from "@playwright/test";
import dotenv from "dotenv";

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

export default defineConfig({
...baseConfig,
// Test settings
timeout: 120000,
retries: process.env.CI ? 3 : 0,
Expand Down
47 changes: 44 additions & 3 deletions docs/guide/core-concepts/playwright-fixtures.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,9 @@ This import replaces the standard Playwright import and provides additional fixt

The `rhdh` fixture is worker-scoped, meaning:

- One deployment is shared across all tests in a worker
- Deployment happens once per worker, not per test
- All tests in the same worker share the same RHDH instance
- One deployment object is shared across all tests in a worker
- You control *when* deployment happens (usually in `test.beforeAll`)
- All tests in the same worker can share the same RHDH instance

```typescript
test.beforeAll(async ({ rhdh }) => {
Expand Down Expand Up @@ -165,6 +165,47 @@ For local development:
- Namespaces are preserved for debugging
- Manual cleanup may be required

## Best Practices for Projects and Spec Files

Each Playwright project name creates a **separate namespace**. The fixture creates one `RHDHDeployment` per worker, and you typically call `rhdh.deploy()` once in `beforeAll`.

**Recommended for overlay workspaces:**

- Use **one Playwright project** named after the workspace.
- Keep **one spec file** per workspace unless you have a strong reason to split.

This keeps deployment cost low and avoids multiple namespaces unless required.

## When You Need Multiple Projects or Spec Files

If requirements differ (different auth, configs, or namespaces), you can:

1. **Use multiple projects** with different names and config overrides.
2. **Manually manage deployments** using `RHDHDeployment` for advanced flows.

Example using multiple projects:

```typescript
export default defineConfig({
projects: [
{ name: "workspace-default" },
{ name: "workspace-guest" },
],
});
```

Example with manual deployment:

```typescript
import { RHDHDeployment } from "rhdh-e2e-test-utils/rhdh";

test.beforeAll(async () => {
const rhdh = new RHDHDeployment("custom-namespace");
await rhdh.configure({ auth: "guest" });
await rhdh.deploy();
});
```

## Example: Complete Test Setup

```typescript
Expand Down
24 changes: 22 additions & 2 deletions docs/guide/deployment/rhdh-deployment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,9 +48,9 @@ test("example", async ({ rhdh }) => {

| Option | Type | Description |
|--------|------|-------------|
| `version` | `string` | RHDH version (e.g., "1.5"). Defaults to `RHDH_VERSION` env var |
| `version` | `string` | RHDH version (e.g., "1.5"). Defaults to `RHDH_VERSION` or `"next"` |
| `namespace` | `string` | Kubernetes namespace. Set via constructor |
| `method` | `"helm" \| "operator"` | Installation method. Defaults to `INSTALLATION_METHOD` env var |
| `method` | `"helm" \| "operator"` | Installation method. Defaults to `INSTALLATION_METHOD` or `"helm"` |
| `auth` | `"guest" \| "keycloak"` | Authentication provider. Defaults to `"keycloak"` |
| `appConfig` | `string` | Path to app-config YAML |
| `secrets` | `string` | Path to secrets YAML |
Expand Down Expand Up @@ -102,6 +102,26 @@ This method:
6. Waits for the deployment to be ready
7. Sets `RHDH_BASE_URL` environment variable

#### Base URL format

The base URL prefix depends on the installation method:

- Helm: `https://redhat-developer-hub-<namespace>.<cluster>`
- Operator: `https://backstage-developer-hub-<namespace>.<cluster>`

#### Helm behavior

Helm deployments perform a scale-down and restart after applying configs to avoid migration locks.

#### Operator version constraints

Operator deployments accept only:

- Semantic versions like `1.5`
- `"next"`

Any other value will throw an error during deployment.

### `waitUntilReady(timeout?)`

Wait for the RHDH deployment to be ready:
Expand Down
70 changes: 3 additions & 67 deletions docs/guide/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,74 +41,10 @@ import { defineConfig } from "rhdh-e2e-test-utils/playwright-config";

## Project Setup

### 1. Create E2E Test Directory
For full project scaffolding (config files, folder structure, and first test), follow:

```bash
mkdir e2e-tests && cd e2e-tests
yarn init -y
```

### 2. Install Dependencies

```bash
yarn add @playwright/test rhdh-e2e-test-utils typescript
```

### 3. Create Configuration Files

Create the following files in your project:

**playwright.config.ts**
```typescript
import { defineConfig } from "rhdh-e2e-test-utils/playwright-config";

export default defineConfig({
projects: [
{
name: "my-plugin",
},
],
});
```

**tsconfig.json**
```json
{
"extends": "rhdh-e2e-test-utils/tsconfig",
"include": ["tests/**/*.ts"]
}
```

**eslint.config.js**
```javascript
import { createEslintConfig } from "rhdh-e2e-test-utils/eslint";

export default createEslintConfig(import.meta.dirname);
```

### 4. Create Test Directory Structure

```bash
mkdir -p tests/config tests/specs
```

Your project structure should look like:

```
e2e-tests/
├── package.json
├── playwright.config.ts
├── tsconfig.json
├── eslint.config.js
├── .env # Environment variables
└── tests/
├── config/
│ ├── app-config-rhdh.yaml # RHDH app configuration
│ ├── dynamic-plugins.yaml # Plugin configuration
│ └── rhdh-secrets.yaml # Secrets template
└── specs/
└── my-plugin.spec.ts # Test files
```
- [Quick Start](/guide/quick-start) - complete setup walkthrough
- [Your First Test](/tutorials/first-test) - step-by-step with explanations

## Next Steps

Expand Down
Loading