docs: document test utility helpers

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. */

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";
 

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 {

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";

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. */

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. */

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";
 

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 = {

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";

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";

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";

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";
 

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";
 

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";
 

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",
   "/",

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";

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";

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 = {

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. */

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,

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";

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";

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";

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";