From 29746cf7a92a3787dc04c21afce96bbe00ac1b30 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 23:53:09 -0400 Subject: [PATCH] docs: document smoke test scripts --- scripts/sqlite-vec-smoke.mjs | 2 ++ scripts/stage-bundled-plugin-runtime.mjs | 5 +++++ scripts/sync-openclaw-label-colors.mjs | 1 + scripts/sync-plugin-sdk-exports.mjs | 1 + ...test-built-bundled-channel-entry-smoke.mjs | 2 ++ scripts/test-built-plugin-singleton.mjs | 1 + scripts/test-built-status-message-runtime.mjs | 21 +++++++++++-------- scripts/test-cli-startup-bench-budget.mjs | 1 + scripts/test-extension-batch.mjs | 13 ++++++++++++ scripts/test-extension.mjs | 1 + 10 files changed, 39 insertions(+), 9 deletions(-) diff --git a/scripts/sqlite-vec-smoke.mjs b/scripts/sqlite-vec-smoke.mjs index 499cebba8ab0..ff6175cf834e 100644 --- a/scripts/sqlite-vec-smoke.mjs +++ b/scripts/sqlite-vec-smoke.mjs @@ -1,3 +1,5 @@ +// Verifies sqlite-vec can load and execute a simple vector query in Node's +// built-in SQLite runtime. import { DatabaseSync } from "node:sqlite"; import { load, getLoadablePath } from "sqlite-vec"; import { formatErrorMessage } from "./lib/error-format.mjs"; diff --git a/scripts/stage-bundled-plugin-runtime.mjs b/scripts/stage-bundled-plugin-runtime.mjs index bbfb10d9a1ae..10da96edd9d4 100644 --- a/scripts/stage-bundled-plugin-runtime.mjs +++ b/scripts/stage-bundled-plugin-runtime.mjs @@ -1,3 +1,5 @@ +// Stages bundled plugin runtime overlays into dist-runtime with SDK aliases and +// Windows-safe symlink fallbacks. import fs from "node:fs"; import path from "node:path"; import { pathToFileURL } from "node:url"; @@ -319,6 +321,9 @@ function stagePluginRuntimeOverlay(sourceDir, targetDir, relativeDir = "") { } } +/** + * Stages runtime plugin entries and aliases used by packaged bundled plugins. + */ export function stageBundledPluginRuntime(params = {}) { const repoRoot = params.cwd ?? params.repoRoot ?? process.cwd(); const distRoot = path.join(repoRoot, "dist"); diff --git a/scripts/sync-openclaw-label-colors.mjs b/scripts/sync-openclaw-label-colors.mjs index f93695c58745..db5cd91e72ba 100644 --- a/scripts/sync-openclaw-label-colors.mjs +++ b/scripts/sync-openclaw-label-colors.mjs @@ -1,4 +1,5 @@ #!/usr/bin/env node +// Synchronizes GitHub label colors to the OpenClaw taxonomy policy. import { execFileSync } from "node:child_process"; const REPO = "openclaw/openclaw"; diff --git a/scripts/sync-plugin-sdk-exports.mjs b/scripts/sync-plugin-sdk-exports.mjs index b7e0aa29ae52..b919a3da67a5 100644 --- a/scripts/sync-plugin-sdk-exports.mjs +++ b/scripts/sync-plugin-sdk-exports.mjs @@ -1,5 +1,6 @@ #!/usr/bin/env node +// Regenerates package.json plugin-sdk export entries from the canonical entry list. import fs from "node:fs"; import path from "node:path"; import { buildPluginSdkPackageExports } from "./lib/plugin-sdk-entries.mjs"; diff --git a/scripts/test-built-bundled-channel-entry-smoke.mjs b/scripts/test-built-bundled-channel-entry-smoke.mjs index 5433b8402182..67b91792a690 100644 --- a/scripts/test-built-bundled-channel-entry-smoke.mjs +++ b/scripts/test-built-bundled-channel-entry-smoke.mjs @@ -1,3 +1,5 @@ +// Smoke-tests packaged bundled channel entrypoints in source and installed +// package layouts. import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import fs from "node:fs"; diff --git a/scripts/test-built-plugin-singleton.mjs b/scripts/test-built-plugin-singleton.mjs index 5c6fd98fe7f3..9ffdcc14b6b2 100644 --- a/scripts/test-built-plugin-singleton.mjs +++ b/scripts/test-built-plugin-singleton.mjs @@ -1,3 +1,4 @@ +// Smoke-tests the built plugin loader singleton and bundled plugin runtime overlay. import assert from "node:assert/strict"; import fs from "node:fs"; import os from "node:os"; diff --git a/scripts/test-built-status-message-runtime.mjs b/scripts/test-built-status-message-runtime.mjs index 64bd66a78240..2b7de5c83cca 100644 --- a/scripts/test-built-status-message-runtime.mjs +++ b/scripts/test-built-status-message-runtime.mjs @@ -1,3 +1,4 @@ +// Smoke-tests that the built status-message runtime bundle is discoverable and loadable. import assert from "node:assert/strict"; import { spawnSync } from "node:child_process"; import fs from "node:fs"; @@ -7,16 +8,18 @@ import { parsePackageRootArg } from "./lib/package-root-args.mjs"; const STATUS_MESSAGE_RUNTIME_RE = /^status-message\.runtime(?:-[A-Za-z0-9_-]+)?\.js$/u; +/** + * Finds the preferred built status-message runtime bundle under dist. + */ export function findBuiltStatusMessageRuntimePath(distDir) { - const candidates = listBuiltStatusMessageRuntimeFiles(distDir) - .toSorted((left, right) => { - const leftHasHash = left !== "status-message.runtime.js"; - const rightHasHash = right !== "status-message.runtime.js"; - if (leftHasHash !== rightHasHash) { - return leftHasHash ? -1 : 1; - } - return left.localeCompare(right); - }); + const candidates = listBuiltStatusMessageRuntimeFiles(distDir).toSorted((left, right) => { + const leftHasHash = left !== "status-message.runtime.js"; + const rightHasHash = right !== "status-message.runtime.js"; + if (leftHasHash !== rightHasHash) { + return leftHasHash ? -1 : 1; + } + return left.localeCompare(right); + }); assert.ok(candidates.length > 0, `missing built status-message runtime bundle under ${distDir}`); diff --git a/scripts/test-cli-startup-bench-budget.mjs b/scripts/test-cli-startup-bench-budget.mjs index 031de44869e8..8e9c4445ff11 100644 --- a/scripts/test-cli-startup-bench-budget.mjs +++ b/scripts/test-cli-startup-bench-budget.mjs @@ -1,3 +1,4 @@ +// Compares CLI startup benchmark reports against checked-in budgets. import { spawnSync } from "node:child_process"; import fs from "node:fs"; import { booleanFlag, intFlag, parseFlagArgs, stringFlag } from "./lib/arg-utils.mjs"; diff --git a/scripts/test-extension-batch.mjs b/scripts/test-extension-batch.mjs index bb72a8ee45b9..90553be8a07d 100644 --- a/scripts/test-extension-batch.mjs +++ b/scripts/test-extension-batch.mjs @@ -1,5 +1,6 @@ #!/usr/bin/env node +// Runs grouped Vitest plans for one or more bundled plugins. import path from "node:path"; import { listTrackedTestFilesForRoots, @@ -22,6 +23,9 @@ function printUsage() { ); } +/** + * Parses comma-separated plugin ids and separates Vitest passthrough args. + */ export function parseExtensionIds(rawArgs) { const normalizedArgs = rawArgs[0] === "--" ? rawArgs.slice(1) : rawArgs; const separatorIndex = normalizedArgs.indexOf("--"); @@ -46,6 +50,9 @@ export function parseExtensionIds(rawArgs) { }; } +/** + * Resolves bounded parallelism for extension test config groups. + */ export function resolveExtensionBatchParallelism(groupCount, env = process.env) { const raw = env[PARALLEL_ENV_KEY]?.trim(); const override = raw ? parsePositiveInt(raw, PARALLEL_ENV_KEY) : 1; @@ -104,6 +111,9 @@ function isExactExcludePath(inputPath) { return !/[*!?[\]{}]/u.test(inputPath); } +/** + * Collects exact --exclude paths so empty groups can be reported accurately. + */ export function parseExactVitestExcludePaths(vitestArgs) { const excludePaths = new Set(); for (let index = 0; index < vitestArgs.length; index += 1) { @@ -163,6 +173,9 @@ async function runPlanGroup(group, params) { }); } +/** + * Runs a resolved extension batch plan, optionally in parallel config groups. + */ export async function runExtensionBatchPlan(batchPlan, params = {}) { const env = params.env ?? process.env; const vitestArgs = params.vitestArgs ?? []; diff --git a/scripts/test-extension.mjs b/scripts/test-extension.mjs index 233ec6922e54..df870372011d 100644 --- a/scripts/test-extension.mjs +++ b/scripts/test-extension.mjs @@ -1,5 +1,6 @@ #!/usr/bin/env node +// Runs the Vitest plan for one bundled plugin by id or path. import { formatErrorMessage } from "./lib/error-format.mjs"; import { resolveExtensionTestPlan } from "./lib/extension-test-plan.mjs"; import { isDirectScriptRun, runVitestBatch } from "./lib/vitest-batch-runner.mjs";