feat(FN-2322): centralize loopback integration test gating

- Add a shared createLoopbackIntegrationTest helper that probes 127.0.0.1 binding once and caches the result
- Use the helper in webhook, websocket, and static asset integration tests to replace duplicated loopback detection logic
- Improve skip diagnostics by including a consistent skip reason and integration scope in skipped test names

packages/dashboard/src/__tests__/loopback-integration-test.ts

@@ -0,0 +1,36 @@
+import http from "node:http";
+import { it } from "vitest";
+
+type IntegrationTestCase = (name: string, fn: () => unknown | Promise<unknown>, timeout?: number) => ReturnType<typeof it>;
+
+const LOOPBACK_SKIP_REASON = "loopback binding to 127.0.0.1 is unavailable in this environment";
+
+let loopbackBindingAvailablePromise: Promise<boolean> | null = null;
+
+async function detectLoopbackBinding(): Promise<boolean> {
+  return await new Promise((resolve) => {
+    const server = http.createServer();
+    server.once("error", () => resolve(false));
+    server.listen(0, "127.0.0.1", () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+
+async function isLoopbackBindingAvailable(): Promise<boolean> {
+  if (!loopbackBindingAvailablePromise) {
+    loopbackBindingAvailablePromise = detectLoopbackBinding();
+  }
+
+  return await loopbackBindingAvailablePromise;
+}
+
+export async function createLoopbackIntegrationTest(scope: string): Promise<IntegrationTestCase> {
+  const loopbackBindingAvailable = await isLoopbackBindingAvailable();
+
+  if (loopbackBindingAvailable) {
+    return (name, fn, timeout) => it(name, fn, timeout);
+  }
+
+  return (name, fn, timeout) => it.skip(`${name} (skipped: ${LOOPBACK_SKIP_REASON}; scope: ${scope})`, fn, timeout);
+}

packages/dashboard/src/__tests__/server-webhook.test.ts

@@ -1,9 +1,10 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { EventEmitter, once } from "node:events";
 import http from "node:http";
-import type { Task, TaskStore, PrInfo, IssueInfo } from "@fusion/core";
+import type { Task, PrInfo, IssueInfo } from "@fusion/core";
 import { createServer } from "../server.js";
 import { getGitHubAppConfig } from "../github-webhooks.js";
+import { createLoopbackIntegrationTest } from "./loopback-integration-test.js";
 
 // Mock the github-webhooks module
 vi.mock("../github-webhooks.js", async () => {
@@ -16,18 +17,7 @@ vi.mock("../github-webhooks.js", async () => {
 
 const mockGetGitHubAppConfig = vi.mocked(getGitHubAppConfig);
 
-async function detectLoopbackBinding(): Promise<boolean> {
-  return await new Promise((resolve) => {
-    const server = http.createServer();
-    server.once("error", () => resolve(false));
-    server.listen(0, "127.0.0.1", () => {
-      server.close(() => resolve(true));
-    });
-  });
-}
-
-const loopbackBindingAvailable = await detectLoopbackBinding();
-const webhookIntegrationTest = loopbackBindingAvailable ? it : it.skip;
+const webhookIntegrationTest = await createLoopbackIntegrationTest("GitHub webhook integration");
 
 class MockStore extends EventEmitter {
   private tasks = new Map<string, Task>();

packages/dashboard/src/__tests__/websocket.test.ts

@@ -1,24 +1,13 @@
 import { EventEmitter, once } from "node:events";
-import http from "node:http";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { WebSocket } from "ws";
 import type { Task } from "@fusion/core";
 import { createServer } from "../server.js";
 import { WebSocketManager } from "../websocket.js";
 import { InMemoryBadgePubSub, type BadgePubSub } from "../badge-pubsub.js";
+import { createLoopbackIntegrationTest } from "./loopback-integration-test.js";
 
-async function detectLoopbackBinding(): Promise<boolean> {
-  return await new Promise((resolve) => {
-    const server = http.createServer();
-    server.once("error", () => resolve(false));
-    server.listen(0, "127.0.0.1", () => {
-      server.close(() => resolve(true));
-    });
-  });
-}
-
-const loopbackBindingAvailable = await detectLoopbackBinding();
-const websocketIntegrationTest = loopbackBindingAvailable ? it : it.skip;
+const websocketIntegrationTest = await createLoopbackIntegrationTest("websocket integration");
 
 class MockSocket extends EventEmitter {
   readyState: number = WebSocket.OPEN;

packages/dashboard/src/server-static-assets.test.ts

@@ -1,19 +1,8 @@
 import express from "express";
 import { describe, expect, it } from "vitest";
-import http from "node:http";
+import { createLoopbackIntegrationTest } from "./__tests__/loopback-integration-test.js";
 
-async function detectLoopbackBinding(): Promise<boolean> {
-  return await new Promise((resolve) => {
-    const server = http.createServer();
-    server.once("error", () => resolve(false));
-    server.listen(0, "127.0.0.1", () => {
-      server.close(() => resolve(true));
-    });
-  });
-}
-
-const loopbackBindingAvailable = await detectLoopbackBinding();
-const staticAssetIntegrationTest = loopbackBindingAvailable ? it : it.skip;
+const staticAssetIntegrationTest = await createLoopbackIntegrationTest("static asset serving");
 
 describe("static asset serving", () => {
   staticAssetIntegrationTest("returns 404 for missing asset paths instead of falling back to index.html", async () => {