docs: document test helpers

test/fixtures/ts-topology/basic/extensions/alpha/src/use.ts

@@ -1,3 +1,4 @@
+// TS topology alpha extension fixture imports SDK members with aliases.
 import { aliasedThing as renamedThing, sharedThing, singleOwnerHelper } from "fixture-sdk";
 import type { SharedType } from "fixture-sdk";
 import * as extra from "fixture-sdk/extra";

test/fixtures/ts-topology/basic/extensions/beta/src/use.ts

@@ -1,3 +1,4 @@
+// TS topology beta extension fixture imports shared SDK members.
 import { sharedThing } from "fixture-sdk";
 import type { SharedType } from "fixture-sdk";
 

test/fixtures/ts-topology/basic/src/internal/use.ts

@@ -1,3 +1,4 @@
+// TS topology internal fixture imports shared SDK members from internal code.
 import { sharedThing } from "fixture-sdk";
 
 export function internalUse() {

test/fixtures/ts-topology/basic/src/lib/shared.ts

@@ -1,3 +1,4 @@
+// TS topology shared fixture helper models a shared library export.
 export function sharedThing() {
   return "shared";
 }

test/fixtures/ts-topology/basic/src/public/extra.ts

@@ -1 +1,2 @@
+// TS topology public extra fixture re-exports shared SDK helpers.
 export { sharedThing } from "../lib/shared.js";

test/fixtures/ts-topology/basic/src/public/index.ts

@@ -1,3 +1,4 @@
+// TS topology public fixture barrel re-exports public SDK members.
 export {
   aliasedThing,
   sharedThing,

test/fixtures/ts-topology/basic/tests/public.test.ts

@@ -1,3 +1,4 @@
+// TS topology public fixture test exercises public fixture SDK exports.
 import { testOnlyThing } from "fixture-sdk";
 
 export function testUse() {

test/helpers/acp-manager-task-state.ts

@@ -1,3 +1,4 @@
+// ACP manager task state helper resets task flow state for ACP tests.
 import { resetTaskFlowRegistryForTests } from "../../src/tasks/task-flow-registry.js";
 import { configureTaskFlowRegistryRuntime } from "../../src/tasks/task-flow-registry.store.js";
 import { findTaskByRunId, resetTaskRegistryForTests } from "../../src/tasks/task-registry.js";

test/helpers/agents/happy-path-prompt-snapshots.ts

@@ -1,3 +1,4 @@
+// Happy path prompt snapshot helper reads expected prompt snapshot files.
 import fs from "node:fs";
 import path from "node:path";
 import type { Model } from "openclaw/plugin-sdk/llm";

test/helpers/agents/llm-stream-simple-mock.ts

@@ -1,3 +1,4 @@
+// Simple LLM stream mock helper builds deterministic streamed responses.
 import { vi } from "vitest";
 
 type LlmMockModule = Record<string, unknown>;

test/helpers/agents/prompt-composition-scenarios.ts

@@ -1,3 +1,4 @@
+// Prompt composition scenarios build reusable agent prompt fixtures.
 import fs from "node:fs/promises";
 import path from "node:path";
 import {

test/helpers/auth-wizard.ts

@@ -1,3 +1,4 @@
+// Auth wizard helpers drive authentication wizard flows in tests.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { vi } from "vitest";

test/helpers/auto-reply/trigger-handling-test-harness.ts

@@ -1,3 +1,4 @@
+// Auto-reply trigger harness builds trigger handling scenarios for tests.
 import { rmSync } from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";

test/helpers/browser-bundled-plugin-fixture.ts

@@ -1,3 +1,4 @@
+// Browser bundled plugin fixtures build browser extension plugin layouts for tests.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";

test/helpers/config/bundled-channel-config-runtime.ts

@@ -1,3 +1,4 @@
+// Bundled channel config runtime helper loads public bundled channel config surfaces.
 import * as bundledChannelModule from "../../../src/channels/plugins/bundled.js";
 import type {
   ChannelConfigRuntimeSchema,

test/helpers/config/config-honor-audit.ts

@@ -1,3 +1,4 @@
+// Config honor audit helper checks config fields against expected consumers.
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";

test/helpers/config/heartbeat-config-honor.inventory.ts

@@ -1,3 +1,4 @@
+// Heartbeat config honor inventory lists heartbeat config ownership rows.
 import type { ConfigHonorInventoryRow } from "./config-honor-audit.js";
 
 // Inventory of heartbeat config keys and the proof paths that should honor them.

test/helpers/config/redact-snapshot-test-hints.ts

@@ -1,3 +1,4 @@
+// Redaction snapshot hints list config UI hints used by redaction tests.
 import type { ConfigUiHints } from "../../../src/config/schema.js";
 
 // Keep this fixture minimal so redaction tests exercise the hint-matching

test/helpers/cron/service-regression-fixtures.ts

@@ -1,3 +1,4 @@
+// Cron service regression fixtures build reusable scheduled job states.
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";

test/helpers/gateway-e2e-harness.test.ts

@@ -1,3 +1,4 @@
+// Gateway E2E harness tests cover helper server and probe behavior.
 import { createServer, type Server } from "node:http";
 import { afterEach, describe, expect, it } from "vitest";
 import { postJson } from "./gateway-e2e-harness.js";

test/helpers/gateway-e2e-harness.ts

@@ -1,3 +1,4 @@
+// Gateway E2E harness starts test gateway processes and HTTP probes.
 import { request as httpRequest } from "node:http";
 import path from "node:path";
 import { GatewayClient } from "../../src/gateway/client.js";

test/helpers/gateway/android-node-capabilities-policy-config.ts

@@ -1,3 +1,4 @@
+// Android node capability policy config fixture describes gateway policy config.
 import type { OpenClawConfig } from "../../../src/config/config.js";
 
 // Test helper for unwrapping gateway config.get response shapes.

test/helpers/gateway/android-node-capabilities-policy-source.ts

@@ -1,3 +1,4 @@
+// Android node capability policy source fixture describes gateway connection inputs.
 import type { GatewayConnectionDetails } from "../../../src/gateway/call.js";
 
 // Test helper for deciding when Android node policy config should be fetched remotely.

test/helpers/image-fixtures.ts

@@ -1,3 +1,4 @@
+// Image fixture helper re-exports shared media fixture paths.
 export {
   createGrayscaleAlphaPngBuffer,
   createNoisyPngBuffer,

test/helpers/infra/heartbeat-runner-channel-plugins.ts

@@ -1,3 +1,4 @@
+// Heartbeat runner channel plugin fixtures build channel plugin contracts for tests.
 import type {
   ChannelId,
   ChannelMessagingAdapter,

test/helpers/live-image-probe.test.ts

@@ -1,3 +1,4 @@
+// Live image probe tests cover generated probe image payloads.
 import { describe, expect, it } from "vitest";
 import { renderCatFacePngBase64, renderSolidColorPngBase64 } from "./live-image-probe.js";
 

test/helpers/live-image-probe.ts

@@ -1,3 +1,4 @@
+// Live image probe helpers build tiny image fixtures for live provider tests.
 import { encodePngRgba, fillPixel } from "../../src/media/png-encode.js";
 
 const GLYPH_ROWS_5X7: Record<string, number[]> = {

test/helpers/media-generation/bundled-provider-builders.ts

@@ -1,3 +1,4 @@
+// Media generation provider builders create bundled provider fixtures for tests.
 import type { OpenClawPluginApi } from "../../../src/plugins/types.js";
 import { loadBundledPluginPublicSurfaceSync } from "../../../src/test-utils/bundled-plugin-public-surface.js";
 

test/helpers/media-generation/runtime-module-mocks.ts

@@ -1,3 +1,4 @@
+// Media generation runtime mocks install mocked runtime modules for tests.
 import { vi } from "vitest";
 import type { OpenClawConfig } from "../../../src/config/config.js";
 import type { ImageGenerationProvider } from "../../../src/image-generation/types.js";

test/helpers/normalize-text.ts

@@ -1,3 +1,4 @@
+// Text normalization helper strips terminal control sequences from test output.
 import { stripAnsi } from "../../packages/terminal-core/src/ansi.js";
 
 // Snapshot text normalization for terminal output tests.

test/helpers/openclaw-test-instance.test.ts

@@ -1,3 +1,4 @@
+// OpenClaw test instance tests cover spawned test instance lifecycle.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it } from "vitest";

test/helpers/openclaw-test-instance.ts

@@ -1,3 +1,4 @@
+// OpenClaw test instance helper spawns isolated OpenClaw processes.
 import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";

test/helpers/paths.ts

@@ -1,3 +1,4 @@
+// Test path helpers resolve repository-relative fixture paths.
 import path from "node:path";
 
 // Cross-platform path containment helper for tests.

test/helpers/pattern-file.ts

@@ -1,3 +1,4 @@
+// Pattern file helpers read file pattern lists for test configuration tests.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";

test/helpers/poll.ts

@@ -1,3 +1,4 @@
+// Poll test helper retries assertions until a timeout.
 import { sleep } from "../../src/utils.js";
 
 // Polling helper for tests that wait on async state.

test/helpers/stt-live-audio.test.ts

@@ -1,3 +1,4 @@
+// STT live audio tests validate live speech-to-text audio fixtures.
 import {
   expectOpenClawLiveTranscriptMarker,
   normalizeTranscriptForMatch,

test/helpers/temp-dir.ts

@@ -1,3 +1,4 @@
+// Test temp directory helper creates and cleans up temporary directories.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";

test/helpers/temp-repo.ts

@@ -1,3 +1,4 @@
+// Temporary repo helper creates Git repositories for integration tests.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";

test/helpers/ui-style-fixtures.ts

@@ -1,3 +1,4 @@
+// UI style fixtures load expected UI style files for tests.
 import { existsSync, readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";

test/helpers/vitest-config-paths.ts

@@ -1,3 +1,4 @@
+// Vitest config path helpers resolve test config fixture paths.
 import path from "node:path";
 
 // Path normalization helpers for Vitest config snapshot assertions.

test/helpers/wizard-prompter.ts

@@ -1,3 +1,4 @@
+// Wizard prompter test helper provides mocked wizard prompt responses.
 import { vi } from "vitest";
 import type { WizardPrompter } from "../../src/wizard/prompts.js";
 

test/mocks/baileys.ts

@@ -1,3 +1,4 @@
+// Baileys mock provides a lightweight WhatsApp socket facade for tests.
 import { EventEmitter } from "node:events";
 import { vi } from "vitest";
 

test/vitest/discord-api-types-gateway-v10-runtime.ts

@@ -1,3 +1,4 @@
+// Discord gateway types runtime helper loads discord-api-types gateway v10 at runtime.
 import { createRequire } from "node:module";
 import type * as DiscordGatewayApiTypes from "discord-api-types/gateway/v10";
 

test/vitest/discord-api-types-payloads-v10-runtime.ts

@@ -1,3 +1,4 @@
+// Discord payload types runtime helper loads discord-api-types payloads at runtime.
 import { createRequire } from "node:module";
 import type * as DiscordPayloadApiTypes from "discord-api-types/payloads/v10";
 

test/vitest/discord-api-types-v10-runtime.ts

@@ -1,3 +1,4 @@
+// Discord API types runtime helper loads discord-api-types v10 at runtime.
 import { createRequire } from "node:module";
 import type * as DiscordApiTypes from "discord-api-types/v10";