docs: document gateway server test suites

src/gateway/server-import-boundary.test.ts

@@ -1,3 +1,5 @@
+// Gateway import-boundary tests keep startup-critical modules lazy and prevent
+// heavyweight cron, doctor, secret, task, and WebSocket handlers from eager loads.
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { describe, expect, it } from "vitest";

src/gateway/server-maintenance.test.ts

@@ -1,3 +1,5 @@
+// Gateway maintenance tests cover periodic cleanup for media, dedupe records,
+// stale chat buffers, expired runs, health summaries, and timer disposal.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { HealthSummary } from "../commands/health.js";
 import type { ChatAbortControllerEntry } from "./chat-abort.js";

src/gateway/server-plugins.test.ts

@@ -1,3 +1,5 @@
+// Gateway plugin tests cover plugin loading, auto-enable, runtime registry setup,
+// request-scope injection, diagnostics, and handler dispatch integration.
 import { afterEach, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
 import type { PluginLookUpTable } from "../plugins/plugin-lookup-table.js";
 import type { PluginRegistry } from "../plugins/registry.js";

src/gateway/server-restart-deferral.test.ts

@@ -1,3 +1,5 @@
+// Restart deferral tests protect queue-depth checks that delay gateway restart
+// until in-flight reply deliveries and command work have drained.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   clearAllDispatchers,

src/gateway/server-runtime-config.test.ts

@@ -1,3 +1,5 @@
+// Runtime config tests cover gateway bind/auth resolution, trusted proxy rules,
+// container defaults, and invalid config rejection before server startup.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { __resetContainerCacheForTest } from "./net.js";
 import { resolveGatewayRuntimeConfig } from "./server-runtime-config.js";

src/gateway/server-startup-config.recovery.test.ts

@@ -1,3 +1,5 @@
+// Startup config recovery tests cover prepared snapshots, plugin metadata,
+// auto-enable behavior, model defaults, and recovery diagnostics.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import type { ConfigFileSnapshot, ModelDefinitionConfig, OpenClawConfig } from "../config/types.js";
 import type { PluginMetadataSnapshot } from "../plugins/plugin-metadata-snapshot.js";

src/gateway/server-startup-config.secrets.test.ts

@@ -1,3 +1,5 @@
+// Startup config secret tests protect gateway token preparation, weak-secret
+// detection, auth profile loading, warning emission, and runtime activation.
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";

src/gateway/server-startup-log.test.ts

@@ -1,3 +1,5 @@
+// Startup log tests cover security warnings, model detail formatting, plugin
+// summaries, bind URLs, ANSI output, and dangerous config reporting.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { stripAnsi } from "../../packages/terminal-core/src/ansi.js";
 import { formatAgentModelStartupDetails, logGatewayStartup } from "./server-startup-log.js";

src/gateway/server-tailscale.test.ts

@@ -1,3 +1,5 @@
+// Tailscale exposure tests cover serve/funnel enablement, preserve-funnel mode,
+// hostname discovery, cleanup handles, and warning paths.
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => ({

src/gateway/server.agent.gateway-server-agent-b.test.ts

@@ -1,3 +1,5 @@
+// Gateway agent integration tests cover channel routing, session context,
+// WebSocket requests, agent event delivery, and provider/runtime error handling.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";

src/gateway/server.agent.subagent-delivery-context.test.ts

@@ -1,3 +1,5 @@
+// Subagent delivery-context tests protect route metadata inheritance for child
+// agent sessions and outbound delivery through channel plugins.
 import fs from "node:fs/promises";
 import { describe, expect, test } from "vitest";
 import type { ChannelPlugin } from "../channels/plugins/types.js";

src/gateway/server.auth.browser-hardening.test.ts

@@ -1,3 +1,5 @@
+// Browser auth hardening tests cover origin, trusted-proxy, signed-device,
+// bootstrap-token, and scope checks for control UI WebSocket clients.
 import { randomUUID } from "node:crypto";
 import os from "node:os";
 import path from "node:path";