From 4295329ec31f02101c2ce0884242e1aa89cbbd8b Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 02:51:28 -0400
Subject: [PATCH] docs: document test utility helpers

---
 src/test-utils/channel-plugin-test-fixtures.ts  | 1 +
 src/test-utils/channel-plugins.test.ts          | 1 +
 src/test-utils/env.test.ts                      | 1 +
 src/test-utils/exec-assertions.ts               | 1 +
 src/test-utils/frozen-time.ts                   | 1 +
 src/test-utils/mock-call-assertions.ts          | 1 +
 src/test-utils/mock-http-response.ts            | 1 +
 src/test-utils/node-process.ts                  | 1 +
 src/test-utils/npm-spec-install-test-helpers.ts | 1 +
 src/test-utils/openclaw-test-state.ts           | 1 +
 src/test-utils/plugin-setup-wizard.ts           | 1 +
 src/test-utils/ports.ts                         | 1 +
 src/test-utils/provider-usage-fetch.ts          | 1 +
 src/test-utils/repo-files.ts                    | 1 +
 src/test-utils/secret-ref-test-vectors.ts       | 1 +
 src/test-utils/session-state-cleanup.ts         | 1 +
 src/test-utils/symlink-rebind-race.ts           | 1 +
 src/test-utils/system-run-prepare-payload.ts    | 1 +
 src/test-utils/talk-test-provider.ts            | 1 +
 src/test-utils/task-registry-runtime.ts         | 1 +
 src/test-utils/temp-dir.ts                      | 1 +
 src/test-utils/temp-home.test.ts                | 1 +
 src/test-utils/temp-home.ts                     | 1 +
 src/test-utils/tracked-temp-dirs.ts             | 1 +
 24 files changed, 24 insertions(+)

diff --git a/src/test-utils/channel-plugin-test-fixtures.ts b/src/test-utils/channel-plugin-test-fixtures.ts
index 0b57d5acaebb..ff41c362b2a5 100644
--- a/src/test-utils/channel-plugin-test-fixtures.ts
+++ b/src/test-utils/channel-plugin-test-fixtures.ts
@@ -1,3 +1,4 @@
+// Fixtures for constructing channel plugins in unit tests.
 import type { ChannelPlugin } from "../channels/plugins/types.plugin.js";
 
 /** Builds the smallest direct-message channel plugin shape used by config tests. */
diff --git a/src/test-utils/channel-plugins.test.ts b/src/test-utils/channel-plugins.test.ts
index d69c4e22dfe9..ff254d343c94 100644
--- a/src/test-utils/channel-plugins.test.ts
+++ b/src/test-utils/channel-plugins.test.ts
@@ -1,3 +1,4 @@
+// Tests channel plugin test registry helpers.
 import { describe, expect, it } from "vitest";
 import { createChannelTestPluginBase, createOutboundTestPlugin } from "./channel-plugins.js";
 
diff --git a/src/test-utils/env.test.ts b/src/test-utils/env.test.ts
index 8dee7eea2eb5..2b7fdfa1d77a 100644
--- a/src/test-utils/env.test.ts
+++ b/src/test-utils/env.test.ts
@@ -1,3 +1,4 @@
+// Tests environment helper behavior for isolated test homes.
 import path from "node:path";
 import { describe, expect, it } from "vitest";
 import {
diff --git a/src/test-utils/exec-assertions.ts b/src/test-utils/exec-assertions.ts
index 4f0ba821d007..fa7ed0b21825 100644
--- a/src/test-utils/exec-assertions.ts
+++ b/src/test-utils/exec-assertions.ts
@@ -1,3 +1,4 @@
+// Assertion helpers for command execution tests and captured output.
 import fs from "node:fs";
 import path from "node:path";
 import { expect } from "vitest";
diff --git a/src/test-utils/frozen-time.ts b/src/test-utils/frozen-time.ts
index e586d9325cd0..c28b9e9a3710 100644
--- a/src/test-utils/frozen-time.ts
+++ b/src/test-utils/frozen-time.ts
@@ -1,3 +1,4 @@
+// Freezes and restores time in tests that assert timestamped behavior.
 import { vi } from "vitest";
 
 /** Freezes Vitest's fake clock for tests that assert timestamps or timers. */
diff --git a/src/test-utils/mock-call-assertions.ts b/src/test-utils/mock-call-assertions.ts
index db45cf60f3c2..b794a7b04d15 100644
--- a/src/test-utils/mock-call-assertions.ts
+++ b/src/test-utils/mock-call-assertions.ts
@@ -1,3 +1,4 @@
+// Assertion helpers for inspecting Vitest mock call payloads.
 import { expect } from "vitest";
 
 /** Returns a mock call with a useful failure when the call is missing. */
diff --git a/src/test-utils/mock-http-response.ts b/src/test-utils/mock-http-response.ts
index 82727f620568..024096c7eed1 100644
--- a/src/test-utils/mock-http-response.ts
+++ b/src/test-utils/mock-http-response.ts
@@ -1,3 +1,4 @@
+// Provides a lightweight ServerResponse mock for HTTP handler tests.
 import type { ServerResponse } from "node:http";
 import { lowercasePreservingWhitespace } from "@openclaw/normalization-core/string-coerce";
 
diff --git a/src/test-utils/node-process.ts b/src/test-utils/node-process.ts
index 6be3095a76e5..24a745c4ee2b 100644
--- a/src/test-utils/node-process.ts
+++ b/src/test-utils/node-process.ts
@@ -1,3 +1,4 @@
+// Test helpers for spawning Node processes and asserting their output.
 import { execFileSync, spawnSync, type SpawnSyncReturns } from "node:child_process";
 
 type NodeEvalArgsOptions = {
diff --git a/src/test-utils/npm-spec-install-test-helpers.ts b/src/test-utils/npm-spec-install-test-helpers.ts
index a582559b7809..bd6ee43097cc 100644
--- a/src/test-utils/npm-spec-install-test-helpers.ts
+++ b/src/test-utils/npm-spec-install-test-helpers.ts
@@ -1,3 +1,4 @@
+// Helpers for package install tests that inspect npm spec output.
 import fs from "node:fs";
 import path from "node:path";
 import { expect } from "vitest";
diff --git a/src/test-utils/openclaw-test-state.ts b/src/test-utils/openclaw-test-state.ts
index 45b5a773da2a..607b7f977cd6 100644
--- a/src/test-utils/openclaw-test-state.ts
+++ b/src/test-utils/openclaw-test-state.ts
@@ -1,3 +1,4 @@
+// Creates isolated OpenClaw state directories for integration-style tests.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/test-utils/plugin-setup-wizard.ts b/src/test-utils/plugin-setup-wizard.ts
index cdfb5a2c98c8..152c909f644c 100644
--- a/src/test-utils/plugin-setup-wizard.ts
+++ b/src/test-utils/plugin-setup-wizard.ts
@@ -1,3 +1,4 @@
+// Mocks plugin setup wizard flows for command and installer tests.
 import { vi, type Mock } from "vitest";
 import { buildChannelSetupWizardAdapterFromSetupWizard } from "../channels/plugins/setup-wizard.js";
 import type { ChannelPlugin } from "../channels/plugins/types.js";
diff --git a/src/test-utils/ports.ts b/src/test-utils/ports.ts
index 282342424bcf..11021b6edf87 100644
--- a/src/test-utils/ports.ts
+++ b/src/test-utils/ports.ts
@@ -1,3 +1,4 @@
+// Allocates available local ports for tests that start servers.
 import { createServer } from "node:net";
 import { isMainThread, threadId } from "node:worker_threads";
 
diff --git a/src/test-utils/provider-usage-fetch.ts b/src/test-utils/provider-usage-fetch.ts
index dd4403ca7966..53afd8787d5c 100644
--- a/src/test-utils/provider-usage-fetch.ts
+++ b/src/test-utils/provider-usage-fetch.ts
@@ -1,3 +1,4 @@
+// Mocks provider usage fetching for tests that assert accounting behavior.
 import { vi } from "vitest";
 import { withFetchPreconnect } from "./fetch-mock.js";
 
diff --git a/src/test-utils/repo-files.ts b/src/test-utils/repo-files.ts
index b283d3300698..99ee233d9ff6 100644
--- a/src/test-utils/repo-files.ts
+++ b/src/test-utils/repo-files.ts
@@ -1,3 +1,4 @@
+// Test helpers for reading repository files through git-aware paths.
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 
diff --git a/src/test-utils/secret-ref-test-vectors.ts b/src/test-utils/secret-ref-test-vectors.ts
index beb0f3407648..ea3f60112839 100644
--- a/src/test-utils/secret-ref-test-vectors.ts
+++ b/src/test-utils/secret-ref-test-vectors.ts
@@ -1,3 +1,4 @@
+// Shared valid and invalid secret reference ids for tests.
 export const VALID_FILE_SECRET_REF_IDS = [
   "value",
   "/",
diff --git a/src/test-utils/session-state-cleanup.ts b/src/test-utils/session-state-cleanup.ts
index 16ec7e8c1ca9..8b560258617d 100644
--- a/src/test-utils/session-state-cleanup.ts
+++ b/src/test-utils/session-state-cleanup.ts
@@ -1,3 +1,4 @@
+// Cleans session-related shared state after tests.
 import { drainSessionWriteLockStateForTest } from "../agents/session-write-lock.js";
 import { clearSessionStoreCaches } from "../config/sessions/store-cache.js";
 import { drainSessionStoreWriterQueuesForTest } from "../config/sessions/store-writer-state.js";
diff --git a/src/test-utils/symlink-rebind-race.ts b/src/test-utils/symlink-rebind-race.ts
index 30013f654e19..755fb9f9203b 100644
--- a/src/test-utils/symlink-rebind-race.ts
+++ b/src/test-utils/symlink-rebind-race.ts
@@ -1,3 +1,4 @@
+// Test helper for simulating symlink rebind races around filesystem reads.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { vi } from "vitest";
diff --git a/src/test-utils/system-run-prepare-payload.ts b/src/test-utils/system-run-prepare-payload.ts
index 07cb5b20b584..d42c46289910 100644
--- a/src/test-utils/system-run-prepare-payload.ts
+++ b/src/test-utils/system-run-prepare-payload.ts
@@ -1,3 +1,4 @@
+// Builds expected system-run payloads for execution approval tests.
 import { formatExecCommand } from "../infra/system-run-command.js";
 
 type SystemRunPrepareInput = {
diff --git a/src/test-utils/talk-test-provider.ts b/src/test-utils/talk-test-provider.ts
index b2f98e2f1724..7031c850c04d 100644
--- a/src/test-utils/talk-test-provider.ts
+++ b/src/test-utils/talk-test-provider.ts
@@ -1,3 +1,4 @@
+// Test provider implementation for chat-style runtime interactions.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 
 /** Test-only speech provider identity used by talk config assertions. */
diff --git a/src/test-utils/task-registry-runtime.ts b/src/test-utils/task-registry-runtime.ts
index 401723eb2280..5e2fa5e8cddc 100644
--- a/src/test-utils/task-registry-runtime.ts
+++ b/src/test-utils/task-registry-runtime.ts
@@ -1,3 +1,4 @@
+// Test runtime helpers for task registry state and deterministic cleanup.
 import {
   configureTaskRegistryRuntime,
   type TaskRegistryStore,
diff --git a/src/test-utils/temp-dir.ts b/src/test-utils/temp-dir.ts
index c82e7416c23c..a3c175b1be12 100644
--- a/src/test-utils/temp-dir.ts
+++ b/src/test-utils/temp-dir.ts
@@ -1,3 +1,4 @@
+// Creates temporary directories with cleanup hooks for tests.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/test-utils/temp-home.test.ts b/src/test-utils/temp-home.test.ts
index ba0b21000ba6..2216186d55b2 100644
--- a/src/test-utils/temp-home.test.ts
+++ b/src/test-utils/temp-home.test.ts
@@ -1,3 +1,4 @@
+// Tests temporary home directory helper setup and cleanup.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/test-utils/temp-home.ts b/src/test-utils/temp-home.ts
index 69905437d59f..72ea16bf1963 100644
--- a/src/test-utils/temp-home.ts
+++ b/src/test-utils/temp-home.ts
@@ -1,3 +1,4 @@
+// Creates isolated temporary home directories for config-heavy tests.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/test-utils/tracked-temp-dirs.ts b/src/test-utils/tracked-temp-dirs.ts
index b0a3bd222e3e..98284430569f 100644
--- a/src/test-utils/tracked-temp-dirs.ts
+++ b/src/test-utils/tracked-temp-dirs.ts
@@ -1,3 +1,4 @@
+// Tracks temporary directories created by tests so leaks can be detected.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";