feat: add auto-fixture for Istanbul E2E coverage collection (#95)

* feat: add auto-fixture for Istanbul E2E coverage collection

- Adds _coverageCollector automatic fixture to test object
- Collects window.__coverage__ from browser after each test
- Writes per-test JSON files to <outputDir>/coverage/
- Enabled via E2E_COLLECT_COVERAGE=1
- Zero overhead when disabled (no page.evaluate or fs operations)
- Designed for use with instrumented dynamic plugin builds

This enables automatic E2E coverage collection for all workspaces
in rhdh-plugin-export-overlays without modifying any test files.

* feat: auto-swap to __coverage images for frontend plugins in PR mode

Implements automatic image tag swap from 'pr_XXX__version' to
'pr_XXX__version__coverage' when E2E_COLLECT_COVERAGE=1 is set
and the plugin is a frontend-plugin.

Changes:
1. Add 'role' field to PluginMetadata and PackageCRD types
2. Parse spec.backstage.role in parseMetadataFile()
3. Swap to __coverage tag in resolvePluginPackages() when:
   - GIT_PR_NUMBER is set (PR mode)
   - E2E_COLLECT_COVERAGE=1
   - Plugin role is 'frontend-plugin'

The regex preserves OCI alias: plugin:tag!alias → plugin:tag__coverage!alias

Only affects PR checks. Nightly mode, {{inherit}}, and local dev
paths are unchanged. Backend plugins skip the swap (no browser coverage).

Implements: #95 (comment)

* fix: use "true" instead of "1" for E2E_COLLECT_COVERAGE env var

For consistency with other boolean env vars in the codebase (like
E2E_NIGHTLY_MODE, USE_NEW_FRONTEND_SYSTEM), change from checking
"1" to checking "true".

Updated in:
- src/playwright/fixtures/test.ts (_coverageCollector fixture)
- src/utils/plugin-metadata.ts (coverage image swap)
- docs/changelog.md (documentation)

Addresses: #95 (comment)

* chore: bump version to 1.1.46

Main branch was updated to 1.1.45, so this PR needs to bump to 1.1.46.

* Apply suggestions from code review

Co-authored-by: Subhash Khileri <subhashkhileri2@gmail.com>

---------

Co-authored-by: Subhash Khileri <subhashkhileri2@gmail.com>

Author: gustavolira

docs/changelog.md

@@ -2,7 +2,11 @@
 
 All notable changes to this project will be documented in this file.
 
-## [1.1.45] - Current
+## [2.1.0] - Current
+
+### Added
+
+- **E2E coverage collection auto-fixture**: New `_coverageCollector` automatic fixture collects Istanbul coverage (`window.__coverage__`) from the browser after each test and writes per-test JSON files to `<outputDir>/coverage/`. Enabled via `E2E_COLLECT_COVERAGE=true`. Zero overhead when disabled — no `page.evaluate` call or fs operations. Designed for use with instrumented dynamic plugin builds (nyc instrument).
 
 ### Fixed
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@red-hat-developer-hub/e2e-test-utils",
-  "version": "1.1.45",
+  "version": "2.1.0",
   "description": "Test utilities for RHDH E2E tests",
   "license": "Apache-2.0",
   "repository": {

src/playwright/fixtures/test.ts

@@ -4,13 +4,16 @@ import { LoginHelper, UIhelper } from "../helpers/index.js";
 import { runOnce } from "../run-once.js";
 import { $ } from "../../utils/bash.js";
 import { WorkspacePaths } from "../../utils/workspace-paths.js";
+import fs from "node:fs";
 import path from "path";
 
 type RHDHDeploymentTestFixtures = {
   rhdh: RHDHDeployment;
   uiHelper: UIhelper;
   loginHelper: LoginHelper;
   autoAnnotations: void;
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  _coverageCollector: void;
 };
 
 type RHDHDeploymentWorkerFixtures = {
@@ -77,6 +80,34 @@ const baseTest = base.extend<
     },
     { auto: true, scope: "test" },
   ],
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  _coverageCollector: [
+    async ({ page }, use, testInfo) => {
+      await use();
+      if (process.env.E2E_COLLECT_COVERAGE !== "true") return;
+      try {
+        const coverage = await page.evaluate(
+          () =>
+            (
+              globalThis as unknown as {
+                // eslint-disable-next-line @typescript-eslint/naming-convention
+                __coverage__?: Record<string, unknown>;
+              }
+            ).__coverage__,
+        );
+        if (!coverage) return;
+        const dir = path.join(testInfo.project.outputDir, "coverage");
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(
+          path.join(dir, `${testInfo.testId}-${Date.now()}.json`),
+          JSON.stringify(coverage),
+        );
+      } catch {
+        // Best-effort: page may have crashed or been closed
+      }
+    },
+    { auto: true, scope: "test" },
+  ],
 });
 
 export const test = Object.assign(baseTest, {

src/utils/plugin-metadata.ts

@@ -14,12 +14,16 @@ export interface PluginMetadata {
   pluginConfig: Record<string, unknown>;
   packageName: string;
   sourceFile: string;
+  role?: string;
 }
 
 interface PackageCRD {
   spec?: {
     packageName?: string;
     dynamicArtifact?: string;
+    backstage?: {
+      role?: string;
+    };
     appConfigExamples?: Array<{
       title?: string;
       content?: Record<string, unknown>;
@@ -227,6 +231,7 @@ export async function parseMetadataFile(
   const packagePath = parsed?.spec?.dynamicArtifact;
   const packageName = parsed?.spec?.packageName;
   const pluginConfig = parsed?.spec?.appConfigExamples?.[0]?.content;
+  const role = parsed?.spec?.backstage?.role;
 
   if (!packagePath) {
     throw new Error(
@@ -244,6 +249,7 @@ export async function parseMetadataFile(
     pluginConfig: pluginConfig || {},
     packageName,
     sourceFile: filePath,
+    role,
   };
 }
 
@@ -482,8 +488,14 @@ async function resolvePluginPackages(
       if (prOciUrls) {
         const prUrl = prOciUrls.get(displayName);
         if (prUrl) {
-          console.log(`[PluginMetadata] PR: ${pkg} → ${prUrl}`);
-          return { ...plugin, package: prUrl };
+          const usesCoverage =
+            process.env.E2E_COLLECT_COVERAGE === "true" &&
+            metadata.role === "frontend-plugin";
+          const resolved = usesCoverage
+            ? prUrl.replace(/(:[^!]+)/, "$1__coverage")
+            : prUrl;
+          console.log(`[PluginMetadata] PR: ${pkg} → ${resolved}`);
+          return { ...plugin, package: resolved };
         }
       }