docs: improve overlay docs and navigation (#27)

Author: subhashkhileri

docs/.vitepress/config.ts

@@ -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",
@@ -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",

docs/guide/configuration/config-files.md

@@ -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/`:
@@ -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:
@@ -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.
 :::

docs/guide/configuration/environment-variables.md

@@ -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
 

docs/guide/core-concepts/playwright-config.md

@@ -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
 
@@ -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",
@@ -81,9 +74,6 @@ export default defineConfig({
       testMatch: "**/another-*.spec.ts",
     },
   ],
-
-  // Add custom reporter
-  reporter: [["list"], ["html"], ["json", { outputFile: "results.json" }]],
 });
 ```
 
@@ -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,

docs/guide/core-concepts/playwright-fixtures.md

@@ -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 }) => {
@@ -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

docs/guide/deployment/rhdh-deployment.md

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

docs/guide/installation.md

@@ -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