test.runOnce implementation

Author: subhashkhileri

docs/CLAUDE.md

@@ -46,7 +46,9 @@ docs/
   import { test, expect } from "@red-hat-developer-hub/e2e-test-utils/test";
 
   test.describe("Feature", () => {
-    test.beforeAll(async ({ rhdh }) => { /* deploy */ });
+    test.beforeAll(async ({ rhdh }) => {
+      await test.runOnce("my-plugin-deploy", async () => { /* deploy */ });
+    });
     test.beforeEach(async ({ loginHelper }) => { /* login */ });
     test("should...", async ({ uiHelper }) => { /* test */ });
   });
@@ -121,6 +123,8 @@ When documenting, reference these source files:
 | Fixtures | `src/playwright/fixtures/test.ts` |
 | Base Config | `src/playwright/base-config.ts` |
 | Global Setup | `src/playwright/global-setup.ts` |
+| Teardown Reporter | `src/playwright/teardown-reporter.ts` |
+| Teardown Namespaces | `src/playwright/teardown-namespaces.ts` |
 
 ## Common Tasks
 
@@ -209,5 +213,6 @@ Base URL is configured as `/rhdh-e2e-test-utils/` in `config.ts`.
 | Helpers | `@red-hat-developer-hub/e2e-test-utils/helpers` | UIhelper, LoginHelper, etc. |
 | Page objects | `@red-hat-developer-hub/e2e-test-utils/pages` | CatalogPage, HomePage, etc. |
 | Utilities | `@red-hat-developer-hub/e2e-test-utils/utils` | KubernetesClientHelper, etc. |
+| Teardown | `@red-hat-developer-hub/e2e-test-utils/teardown` | Custom namespace teardown registration |
 | ESLint | `@red-hat-developer-hub/e2e-test-utils/eslint` | ESLint config |
 | TypeScript | `@red-hat-developer-hub/e2e-test-utils/tsconfig` | TSConfig base |

docs/api/playwright/base-config.md

@@ -59,7 +59,7 @@ Raw base configuration object. Use for advanced customization.
   retries: Number(process.env.PLAYWRIGHT_RETRIES ?? 0),
   workers: process.env.PLAYWRIGHT_WORKERS || "50%",
   outputDir: "node_modules/.cache/e2e-test-results",
-  reporter: [["list"], ["html"], ["json"]],
+  reporter: [["list"], ["html"], ["json"], ["teardown-reporter"]],
   use: {
     viewport: { width: 1920, height: 1080 },
     video: { mode: "retain-on-failure", size: { width: 1280, height: 720 } },

docs/api/playwright/test-fixtures.md

@@ -16,12 +16,14 @@ import { test, expect } from "@red-hat-developer-hub/e2e-test-utils/test";
 
 **Type:** `RHDHDeployment`
 
-Shared RHDH deployment across all tests in a worker.
+Shared RHDH deployment across all tests in a worker. Wrap expensive setup in `test.runOnce` to avoid re-deploying when workers restart after test failures.
 
 ```typescript
 test.beforeAll(async ({ rhdh }) => {
-  await rhdh.configure({ auth: "keycloak" });
-  await rhdh.deploy();
+  await test.runOnce("my-plugin-deploy", async () => {
+    await rhdh.configure({ auth: "keycloak" });
+    await rhdh.deploy();
+  });
 });
 
 test("access rhdh", async ({ rhdh }) => {
@@ -80,6 +82,30 @@ test("using baseURL", async ({ page, baseURL }) => {
 });
 ```
 
+## `test.runOnce`
+
+```typescript
+test.runOnce(key: string, fn: () => Promise<void> | void): Promise<boolean>
+```
+
+Executes `fn` exactly once per test run, even across worker restarts. Returns `true` if executed, `false` if skipped. Useful for expensive or persistent operations (deployments, database seeding, service provisioning) that should not repeat after a worker restart.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `key` | `string` | Unique identifier for this operation |
+| `fn` | `() => Promise<void> \| void` | Function to execute once |
+
+```typescript
+test.beforeAll(async ({ rhdh }) => {
+  await test.runOnce("my-deploy", async () => {
+    await rhdh.configure({ auth: "keycloak" });
+    await rhdh.deploy();
+  });
+});
+```
+
+See [Playwright Fixtures — `test.runOnce`](/guide/core-concepts/playwright-fixtures#test-runonce-—-execute-a-function-once-per-test-run) for detailed usage and examples.
+
 ## Exported Types
 
 ```typescript
@@ -95,8 +121,10 @@ import { test, expect } from "@red-hat-developer-hub/e2e-test-utils/test";
 
 test.describe("My Tests", () => {
   test.beforeAll(async ({ rhdh }) => {
-    await rhdh.configure({ auth: "keycloak" });
-    await rhdh.deploy();
+    await test.runOnce("my-plugin-deploy", async () => {
+      await rhdh.configure({ auth: "keycloak" });
+      await rhdh.deploy();
+    });
   });
 
   test.beforeEach(async ({ page, loginHelper }) => {

docs/changelog.md

@@ -2,7 +2,17 @@
 
 All notable changes to this project will be documented in this file.
 
-## [1.1.13] - Current
+## [1.1.14] - Current
+
+### Added
+- **`test.runOnce(key, fn)`**: Execute a function exactly once per test run, even across worker restarts. Prevents re-running expensive operations (deployments, service provisioning, data seeding) when Playwright creates new workers after test failures.
+- **Teardown reporter**: Built-in Playwright reporter that automatically deletes Kubernetes namespaces after all tests complete. Active only in CI (`process.env.CI`).
+- **`registerTeardownNamespace(projectName, namespace)`**: Register custom namespaces for automatic cleanup. Import from `@red-hat-developer-hub/e2e-test-utils/teardown`.
+
+### Changed
+- Namespace cleanup moved from worker fixture to teardown reporter to prevent premature deletion on test failures.
+
+## [1.1.13]
 
 ### Added
 - Support for GitHub authentication provider

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

@@ -154,16 +154,103 @@ export default defineConfig({
 });
 ```
 
-## Auto-Cleanup
+## `test.runOnce` — Execute a Function Once Per Test Run
 
-In CI environments (when `CI` environment variable is set):
+Playwright's `beforeAll` runs once **per worker**, not once per test run. When a test fails, Playwright kills the worker and creates a new one for remaining tests — causing `beforeAll` to run again. For operations that are expensive or produce persistent side effects, this leads to unnecessary re-execution.
 
-- Namespaces are automatically deleted after tests complete
-- Prevents resource accumulation on shared clusters
+`test.runOnce` ensures a function executes **exactly once per test run**, even across worker restarts:
 
-For local development:
-- Namespaces are preserved for debugging
-- Manual cleanup may be required
+```typescript
+test.beforeAll(async ({ rhdh }) => {
+  await test.runOnce("my-plugin-deploy", async () => {
+    await rhdh.configure({ auth: "keycloak" });
+    await rhdh.deploy();
+  });
+});
+```
+
+### How It Works
+
+- Uses file-based flags scoped to the Playwright runner process
+- When a worker restarts after a test failure, `runOnce` detects the flag and skips
+- Any state created by the function (deployments, databases, services) stays alive
+- Flags reset automatically between test runs
+
+### When to Use
+
+Use `test.runOnce` when your `beforeAll` performs an operation that:
+- Is **expensive** (deployments, database seeding, service provisioning)
+- Creates **persistent state** that survives beyond the worker process (Kubernetes resources, external services, test data)
+- Should **not repeat** once successfully completed
+
+Common examples:
+- RHDH deployment (`rhdh.deploy()`)
+- External service deployment (customization providers, mock APIs)
+- Database seeding or migration
+- Any setup script that takes significant time
+
+### Key: Unique Identifier
+
+The `key` parameter must be unique across all `runOnce` calls in your test run. Use a descriptive name:
+
+```typescript
+// Deploy RHDH
+await test.runOnce("tech-radar-deploy", async () => {
+  await rhdh.deploy();
+});
+
+// Deploy an external service
+await test.runOnce("tech-radar-data-provider", async () => {
+  await $`bash ${setupScript} ${namespace}`;
+});
+
+// Seed test data
+await test.runOnce("catalog-seed-data", async () => {
+  await apiHelper.importEntity("https://example.com/catalog-info.yaml");
+});
+```
+
+## Namespace Cleanup (Teardown)
+
+In CI environments (`CI` environment variable is set), namespaces are automatically deleted after all tests complete. This is handled by a built-in **teardown reporter** that:
+
+1. Runs in the main Playwright process (survives worker restarts)
+2. Waits for **all tests** in a project to finish
+3. Deletes the namespace matching the project name
+
+### Default Behavior
+
+No configuration needed. The namespace is derived from your project name:
+
+```typescript
+// playwright.config.ts
+projects: [
+  { name: "tech-radar" },   // Namespace "tech-radar" deleted after all tests
+  { name: "catalog" },      // Namespace "catalog" deleted after all tests
+]
+```
+
+### Custom Namespaces
+
+If you deploy to a namespace that differs from the project name, register it for cleanup:
+
+```typescript
+import { registerTeardownNamespace } from "@red-hat-developer-hub/e2e-test-utils/teardown";
+
+test.beforeAll(async ({ rhdh }) => {
+  await test.runOnce("custom-deploy", async () => {
+    await rhdh.configure({ namespace: "my-custom-ns", auth: "keycloak" });
+    await rhdh.deploy();
+    registerTeardownNamespace("my-project", "my-custom-ns");
+  });
+});
+```
+
+Multiple namespaces per project are supported — all registered namespaces are deleted after that project's tests complete.
+
+### Local Development
+
+Namespaces are **not** deleted locally (only in CI). This preserves deployments for debugging.
 
 ## Best Practices for Projects and Spec Files
 
@@ -213,12 +300,14 @@ import { test, expect } from "@red-hat-developer-hub/e2e-test-utils/test";
 
 test.describe("My Plugin Tests", () => {
   test.beforeAll(async ({ rhdh }) => {
-    await rhdh.configure({
-      auth: "keycloak",
-      appConfig: "tests/config/app-config.yaml",
-      dynamicPlugins: "tests/config/plugins.yaml",
+    await test.runOnce("my-plugin-deploy", async () => {
+      await rhdh.configure({
+        auth: "keycloak",
+        appConfig: "tests/config/app-config.yaml",
+        dynamicPlugins: "tests/config/plugins.yaml",
+      });
+      await rhdh.deploy();
     });
-    await rhdh.deploy();
   });
 
   test.beforeEach(async ({ page, loginHelper }) => {

docs/guide/deployment/rhdh-deployment.md

@@ -33,8 +33,10 @@ import { test } from "@red-hat-developer-hub/e2e-test-utils/test";
 
 test.beforeAll(async ({ rhdh }) => {
   // rhdh is already instantiated with namespace from project name
-  await rhdh.configure({ auth: "keycloak" });
-  await rhdh.deploy();
+  await test.runOnce("my-plugin-deploy", async () => {
+    await rhdh.configure({ auth: "keycloak" });
+    await rhdh.deploy();
+  });
 });
 
 test("example", async ({ rhdh }) => {
@@ -176,7 +178,7 @@ await deployment.teardown();
 ```
 
 ::: warning
-This permanently deletes all resources in the namespace. In CI, this happens automatically.
+You typically don't need to call this manually. In CI, the built-in teardown reporter automatically deletes namespaces after all tests complete. See [Namespace Cleanup](/guide/core-concepts/playwright-fixtures#namespace-cleanup-teardown).
 :::
 
 ## Properties
@@ -259,21 +261,23 @@ import { test } from "@red-hat-developer-hub/e2e-test-utils/test";
 import { $ } from "@red-hat-developer-hub/e2e-test-utils/utils";
 
 test.beforeAll(async ({ rhdh }) => {
-  const namespace = rhdh.deploymentConfig.namespace;
+  await test.runOnce("my-plugin-deploy", async () => {
+    const namespace = rhdh.deploymentConfig.namespace;
 
-  // Configure RHDH
-  await rhdh.configure({ auth: "keycloak" });
+    // Configure RHDH
+    await rhdh.configure({ auth: "keycloak" });
 
-  // Run custom setup before deployment
-  await $`bash scripts/setup.sh ${namespace}`;
+    // Run custom setup before deployment
+    await $`bash scripts/setup.sh ${namespace}`;
 
-  // Set runtime environment variables
-  process.env.MY_CUSTOM_URL = await rhdh.k8sClient.getRouteLocation(
-    namespace,
-    "my-service"
-  );
+    // Set runtime environment variables
+    process.env.MY_CUSTOM_URL = await rhdh.k8sClient.getRouteLocation(
+      namespace,
+      "my-service"
+    );
 
-  // Deploy RHDH (uses env vars set above)
-  await rhdh.deploy();
+    // Deploy RHDH (uses env vars set above)
+    await rhdh.deploy();
+  });
 });
 ```