From 4a93974a907ea441334cdfd0d01ed30e1539b4e7 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 15:39:01 -0400 Subject: [PATCH] docs: document provider policy tests --- src/agents/owner-display.test.ts | 2 ++ src/agents/path-policy.test.ts | 2 ++ src/agents/plugin-text-transforms.test.ts | 3 +++ src/agents/prompt-composition.test.ts | 3 +++ src/agents/provider-api-families.test.ts | 1 + src/agents/provider-attribution.test.ts | 4 ++++ 6 files changed, 15 insertions(+) diff --git a/src/agents/owner-display.test.ts b/src/agents/owner-display.test.ts index ea55a30d61e..71fb9ef94a3 100644 --- a/src/agents/owner-display.test.ts +++ b/src/agents/owner-display.test.ts @@ -1,3 +1,4 @@ +// Verifies owner display hashing uses a dedicated secret and raw mode disables it. import { describe, expect, it } from "vitest"; import type { OpenClawConfig } from "../config/types.openclaw.js"; import { ensureOwnerDisplaySecret, resolveOwnerDisplaySetting } from "./owner-display.js"; @@ -18,6 +19,7 @@ describe("resolveOwnerDisplaySetting", () => { }); it("does not fall back to gateway tokens when hash secret is missing", () => { + // Gateway auth tokens are unrelated secrets and must never seed owner hashes. const cfg = { commands: { ownerDisplay: "hash", diff --git a/src/agents/path-policy.test.ts b/src/agents/path-policy.test.ts index 89a812a6d6f..982ab63cb89 100644 --- a/src/agents/path-policy.test.ts +++ b/src/agents/path-policy.test.ts @@ -1,3 +1,4 @@ +// Verifies workspace-relative path policy across POSIX and Windows semantics. import { beforeEach, describe, expect, it, vi } from "vitest"; import { withMockedWindowsPlatform } from "../test-utils/vitest-spies.js"; @@ -11,6 +12,7 @@ import { toRelativeWorkspacePath } from "./path-policy.js"; describe("toRelativeWorkspacePath (windows semantics)", () => { beforeEach(() => { + // Sandbox input resolution is not under test; return normalized input paths directly. resolveSandboxInputPathMock.mockReset(); resolveSandboxInputPathMock.mockImplementation((filePath: string) => filePath); }); diff --git a/src/agents/plugin-text-transforms.test.ts b/src/agents/plugin-text-transforms.test.ts index c1542d4a9e8..ebb0251f1f6 100644 --- a/src/agents/plugin-text-transforms.test.ts +++ b/src/agents/plugin-text-transforms.test.ts @@ -1,3 +1,4 @@ +// Verifies plugin text transforms rewrite prompts and streamed assistant output. import type { StreamFn } from "openclaw/plugin-sdk/agent-core"; import { createAssistantMessageEventStream, @@ -20,6 +21,7 @@ const model = { } as Model<"openai-responses">; function makeAssistantMessage(text: string): AssistantMessage { + // Output transform tests need a complete assistant message with visible text. return { role: "assistant", content: [{ type: "text", text }], @@ -106,6 +108,7 @@ describe("plugin text transforms", () => { }); it("wraps stream functions with inbound and outbound replacements", async () => { + // The wrapper mutates text-only blocks while preserving non-text content. let capturedContext: Context | undefined; const baseStreamFn: StreamFn = (_model, context) => { capturedContext = context; diff --git a/src/agents/prompt-composition.test.ts b/src/agents/prompt-composition.test.ts index 5e4f0bca228..aeb1715ebf5 100644 --- a/src/agents/prompt-composition.test.ts +++ b/src/agents/prompt-composition.test.ts @@ -1,3 +1,4 @@ +// Verifies prompt composition invariants across generated agent scenarios. import { afterAll, beforeAll, describe, expect, it } from "vitest"; import { createPromptCompositionScenarios, @@ -7,6 +8,7 @@ import { type ScenarioFixture = Awaited>; function getTurn(scenario: PromptScenario, id: string) { + // Scenario assertions use named turns so failures identify the prompt boundary. const turn = scenario.turns.find((entry) => entry.id === id); if (!turn) { throw new Error(`expected turn ${scenario.scenario}:${id}`); @@ -23,6 +25,7 @@ function getScenario(fixture: ScenarioFixture, id: string): PromptScenario { } function countOccurrences(text: string, needle: string): number { + // Avoid regex escaping when checking exact prompt-body duplication. if (!needle) { return 0; } diff --git a/src/agents/provider-api-families.test.ts b/src/agents/provider-api-families.test.ts index 61daa179fac..78598c8d5b0 100644 --- a/src/agents/provider-api-families.test.ts +++ b/src/agents/provider-api-families.test.ts @@ -1,3 +1,4 @@ +// Verifies provider API family helpers gate GPT parallel tool-call payloads. import { describe, expect, it } from "vitest"; import { supportsGptParallelToolCallsPayload } from "./provider-api-families.js"; diff --git a/src/agents/provider-attribution.test.ts b/src/agents/provider-attribution.test.ts index 61736353942..a69f1a3b751 100644 --- a/src/agents/provider-attribution.test.ts +++ b/src/agents/provider-attribution.test.ts @@ -1,6 +1,8 @@ +// Verifies provider attribution headers and endpoint classification policies. import { describe, expect, it, vi } from "vitest"; function expectRecordFields(record: unknown, expected: Record) { + // Policy helpers return broad records; assertions pin only the relevant fields. if (!record || typeof record !== "object") { throw new Error("Expected record"); } @@ -13,6 +15,7 @@ function expectRecordFields(record: unknown, expected: Record) const providerEndpointPlugins = vi.hoisted(() => [ { + // Mirrors manifest-declared endpoint metadata without loading real plugins. providerEndpoints: [ { endpointClass: "openai-public", hosts: ["api.openai.com"] }, { endpointClass: "openai", hosts: ["chatgpt.com"] }, @@ -239,6 +242,7 @@ describe("provider attribution", () => { }); it("lists the current attribution support matrix", () => { + // Matrix order is user-facing evidence for docs/review summaries. expect( listProviderAttributionPolicies({ OPENCLAW_VERSION: "2026.3.22" }).map((policy) => [ policy.provider,