@elizaos/autonomous 2.0.0-alpha.10

package/src/test-support/process-helpers.ts

@@ -0,0 +1,35 @@
+import type { ChildProcess } from "node:child_process";
+import { EventEmitter } from "node:events";
+
+type MockSpawnOptions = {
+  exitCode: number;
+  stderrOutput?: string;
+  emitError?: Error;
+};
+
+/**
+ * Create a lightweight mocked ChildProcess that emits either an error event
+ * or a close event (with optional stderr output) on the next tick.
+ */
+export function createMockChildProcess(
+  options: MockSpawnOptions,
+): ChildProcess {
+  const child = new EventEmitter() as ChildProcess;
+  const stderrEmitter = new EventEmitter();
+  Object.defineProperty(child, "stderr", { value: stderrEmitter });
+  Object.defineProperty(child, "stdin", { value: null });
+  Object.defineProperty(child, "stdout", { value: null });
+
+  process.nextTick(() => {
+    if (options.emitError) {
+      child.emit("error", options.emitError);
+      return;
+    }
+    if (options.stderrOutput) {
+      stderrEmitter.emit("data", Buffer.from(options.stderrOutput));
+    }
+    child.emit("close", options.exitCode);
+  });
+
+  return child;
+}

package/src/test-support/route-test-helpers.ts

@@ -0,0 +1,113 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { createMockHttpResponse } from "./test-helpers";
+
+export type RouteBody = Record<string, unknown>;
+
+export type RouteInvocationResult<TPayload = unknown> = {
+  handled: boolean;
+  status: number;
+  payload: TPayload;
+};
+
+export type RouteInvokeArgs<TBody = RouteBody, TRuntime = unknown> = {
+  method: string;
+  pathname: string;
+  url?: string;
+  body?: TBody | null;
+  runtimeOverride?: TRuntime;
+  headers?: { host?: string };
+};
+
+export type RouteRequestContext<TBody, TRuntime> = {
+  req: IncomingMessage;
+  res: ServerResponse;
+  method: string;
+  pathname: string;
+  runtime: TRuntime;
+  readJsonBody: () => Promise<TBody | null>;
+  json: (_res: ServerResponse, data: unknown, status?: number) => void;
+  error: (_res: ServerResponse, message: string, status?: number) => void;
+};
+
+type RouteInvokerOptions<TRuntime = unknown> =
+  | {
+      runtime: TRuntime;
+      runtimeProvider?: undefined;
+    }
+  | {
+      runtime?: undefined;
+      runtimeProvider: () => TRuntime;
+    };
+
+export function createRouteInvoker<
+  TBody = RouteBody,
+  TRuntime = unknown,
+  TPayload = unknown,
+>(
+  handler: (ctx: RouteRequestContext<TBody, TRuntime>) => Promise<boolean>,
+  options: RouteInvokerOptions<TRuntime>,
+): (
+  args: RouteInvokeArgs<TBody, TRuntime>,
+) => Promise<RouteInvocationResult<TPayload>> {
+  return async (args) => {
+    const capturedRuntime =
+      options.runtimeProvider === undefined
+        ? options.runtime
+        : options.runtimeProvider();
+
+    const status = 200;
+    const payload = {} as TPayload;
+
+    const response = {
+      hasPayload: false,
+      status,
+      payload,
+    };
+
+    const { res, getStatus, getJson } = createMockHttpResponse<TPayload>();
+
+    const req = {
+      url: args.url ?? args.pathname,
+      headers: { host: args.headers?.host ?? "localhost:2138" },
+    } as IncomingMessage;
+
+    const runtime =
+      args.runtimeOverride === undefined
+        ? capturedRuntime
+        : args.runtimeOverride;
+
+    const handled = await handler({
+      req,
+      res,
+      method: args.method,
+      pathname: args.pathname,
+      runtime: runtime as TRuntime,
+      readJsonBody: async () => {
+        const body = args.body ?? null;
+        return (body as TBody | null) ?? null;
+      },
+      json: (_response, data, status = 200) => {
+        response.hasPayload = true;
+        response.status = status;
+        response.payload = data as TPayload;
+      },
+      error: (_response, message, status = 400) => {
+        response.hasPayload = true;
+        response.status = status;
+        response.payload = { error: message } as TPayload;
+      },
+    });
+
+    if (!response.hasPayload) {
+      response.status = getStatus();
+      response.payload = getJson();
+      response.hasPayload = true;
+    }
+
+    return {
+      handled,
+      status: response.status,
+      payload: response.payload,
+    };
+  };
+}

package/src/test-support/test-helpers.ts

@@ -0,0 +1,304 @@
+import { EventEmitter } from "node:events";
+import { existsSync } from "node:fs";
+import type http from "node:http";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { vi } from "vitest";
+
+/**
+ * Test helper utilities shared across unit tests.
+ */
+
+const OPTIONAL_IMPORT_ERROR_MARKERS = [
+  "Cannot find module",
+  "Cannot find package",
+  "ERR_MODULE_NOT_FOUND",
+  "MODULE_NOT_FOUND",
+  "Dynamic require of",
+  "native addon module",
+  "Failed to resolve entry",
+  "tfjs_binding",
+  "NAPI_MODULE_NOT_FOUND",
+  "spec not found",
+];
+
+/** Standardized test result for mocked updater checks. */
+export type MockUpdateCheckResult = {
+  updateAvailable: boolean;
+  currentVersion: string;
+  latestVersion: string | null;
+  channel: string;
+  distTag: string;
+  cached: boolean;
+  error: string | null;
+};
+
+/** Snapshot and restore the configured environment variables around a test. */
+export function createEnvSandbox(keys: readonly string[]) {
+  const backup: Record<string, string | undefined> = {};
+
+  function clear(): void {
+    for (const key of keys) {
+      backup[key] = process.env[key];
+      delete process.env[key];
+    }
+  }
+
+  function restore(): void {
+    for (const key of keys) {
+      if (backup[key] === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = backup[key];
+      }
+    }
+  }
+
+  return { clear, restore };
+}
+
+export type PluginModuleShape = {
+  [key: string]: unknown;
+  default?: unknown;
+  plugin?: unknown;
+};
+
+/** Loose plugin-shape predicate used in dynamic test imports across suites. */
+export function looksLikePlugin(value: unknown): value is { name: string } {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    typeof (value as Record<string, unknown>).name === "string"
+  );
+}
+
+/** Extract a plugin-like object from a dynamic module export shape. */
+export function extractPlugin(mod: PluginModuleShape): { name: string } | null {
+  if (looksLikePlugin(mod.default)) return mod.default;
+  if (looksLikePlugin(mod.plugin)) return mod.plugin;
+  if (looksLikePlugin(mod)) return mod;
+  for (const key of Object.keys(mod)) {
+    if (key === "default" || key === "plugin") continue;
+    if (looksLikePlugin(mod[key])) return mod[key] as { name: string };
+  }
+  return null;
+}
+
+/** Check whether a package name can be resolved for dynamic import. */
+export function isPackageImportResolvable(packageName: string): boolean {
+  const require = createRequire(import.meta.url);
+  try {
+    require.resolve(packageName);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Check whether a dependency specifier should be treated as a workspace-local version. */
+export function isWorkspaceDependency(version: string | undefined): boolean {
+  return (
+    typeof version === "string" &&
+    (version.startsWith(".") || version.startsWith("workspace:"))
+  );
+}
+
+const DISCORD_PLUGIN_PACKAGE_NAME = "@elizaos/plugin-discord";
+const DISCORD_PLUGIN_LOCAL_ENTRY_CANDIDATES = [
+  "../plugins/plugin-discord/typescript/dist/index",
+  "../plugins/plugin-discord/dist/index",
+] as const;
+
+/**
+ * Resolve the Discord plugin import specifier.
+ * Prefers package resolution, then falls back to local plugin checkout paths.
+ */
+export function resolveDiscordPluginImportSpecifier(): string | null {
+  if (isPackageImportResolvable(DISCORD_PLUGIN_PACKAGE_NAME)) {
+    return DISCORD_PLUGIN_PACKAGE_NAME;
+  }
+
+  const helperDir = path.dirname(fileURLToPath(import.meta.url));
+  const packageRoot = path.resolve(helperDir, "..", "..");
+
+  for (const relativeEntryPath of DISCORD_PLUGIN_LOCAL_ENTRY_CANDIDATES) {
+    const absoluteEntryPath = path.resolve(packageRoot, relativeEntryPath);
+    if (existsSync(absoluteEntryPath)) {
+      return pathToFileURL(absoluteEntryPath).href;
+    }
+  }
+
+  return null;
+}
+
+/** Build a mock update check result with deterministic defaults. */
+export function buildMockUpdateCheckResult(
+  overrides: Partial<MockUpdateCheckResult> = {},
+): MockUpdateCheckResult {
+  return {
+    updateAvailable: false,
+    currentVersion: "2.0.0",
+    latestVersion: "2.0.0",
+    channel: "stable",
+    distTag: "latest",
+    cached: false,
+    error: null,
+    ...overrides,
+  };
+}
+
+/** Small utility to wait for asynchronous side-effects in tests. */
+export function waitMs(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+type MockResponsePayload<T> = {
+  res: http.ServerResponse & {
+    _status: number;
+    _body: string;
+    writeHead: (statusCode: number) => void;
+  };
+  getStatus: () => number;
+  getJson: () => T;
+};
+
+type MockBodyChunk = string | Buffer;
+
+export type MockRequestOptions = {
+  method?: string;
+  url?: string;
+  headers?: Record<string, string>;
+  body?: unknown;
+  bodyChunks?: MockBodyChunk[];
+  json?: boolean;
+};
+
+/** Create a lightweight mocked HTTP response used by handler tests. */
+export function createMockHttpResponse<T = unknown>(): MockResponsePayload<T> {
+  let statusCode = 200;
+  let legacyStatus = 0;
+  let payload = "";
+
+  const res = {
+    set statusCode(value: number) {
+      statusCode = value;
+      legacyStatus = value;
+    },
+    get statusCode() {
+      return statusCode;
+    },
+    _status: legacyStatus,
+    _body: payload,
+    setHeader: () => undefined,
+    writeHead: (value: number) => {
+      statusCode = value;
+      legacyStatus = value;
+    },
+    end: (chunk?: string | Buffer) => {
+      payload = chunk ? chunk.toString() : "";
+      res._body = payload;
+      legacyStatus = statusCode;
+      res._status = legacyStatus;
+    },
+  } as unknown as http.ServerResponse & {
+    _status: number;
+    _body: string;
+    writeHead: (statusCode: number) => void;
+  };
+
+  return {
+    res,
+    getStatus: () => statusCode,
+    getJson: () => (payload ? (JSON.parse(payload) as T) : (null as T)),
+  };
+}
+
+export function createMockHeadersRequest(
+  headers: Record<string, string> = {},
+  options: Omit<MockRequestOptions, "headers" | "body"> = {},
+): http.IncomingMessage & { destroy: () => void } {
+  return createMockIncomingMessage({
+    ...options,
+    headers,
+  });
+}
+
+export function createMockIncomingMessage({
+  method = "GET",
+  url = "/",
+  headers = { host: "localhost:2138" },
+  body,
+  bodyChunks,
+  json = false,
+}: MockRequestOptions): http.IncomingMessage & { destroy: () => void } {
+  const req = new EventEmitter() as http.IncomingMessage &
+    EventEmitter & { destroy: () => void };
+
+  req.method = method;
+  req.url = url;
+  req.headers = headers;
+  req.destroy = vi.fn();
+
+  const chunks: Buffer[] = [];
+
+  if (bodyChunks !== undefined) {
+    for (const chunk of bodyChunks) {
+      chunks.push(
+        typeof chunk === "string" ? Buffer.from(chunk, "utf-8") : chunk,
+      );
+    }
+  } else if (body !== undefined) {
+    const encoded =
+      typeof body === "string"
+        ? Buffer.from(body, "utf-8")
+        : body instanceof Buffer
+          ? body
+          : json
+            ? Buffer.from(JSON.stringify(body), "utf-8")
+            : Buffer.from(String(body), "utf-8");
+    chunks.push(encoded);
+  }
+
+  for (const chunk of chunks) {
+    queueMicrotask(() => req.emit("data", chunk));
+  }
+  queueMicrotask(() => req.emit("end"));
+
+  return req;
+}
+
+export function createMockJsonRequest(
+  body: unknown,
+  options: Omit<MockRequestOptions, "body" | "json"> = {},
+): http.IncomingMessage & { destroy: () => void } {
+  return createMockIncomingMessage({
+    ...options,
+    body,
+    json: true,
+  });
+}
+
+/** Return true when optional plugin imports are intentionally unavailable in this env. */
+export function isOptionalImportError(
+  error: unknown,
+  extraMarkers: readonly string[] = [],
+): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return OPTIONAL_IMPORT_ERROR_MARKERS.concat(extraMarkers).some((marker) =>
+    message.includes(marker),
+  );
+}
+
+/** Safely import optional plugin modules while allowing hard failures to bubble. */
+export async function tryOptionalDynamicImport<T>(
+  moduleName: string,
+  markers?: readonly string[],
+): Promise<T | null> {
+  try {
+    return (await import(moduleName)) as T;
+  } catch (error) {
+    if (isOptionalImportError(error, markers)) return null;
+    throw error;
+  }
+}

package/src/testing/index.ts

@@ -0,0 +1,3 @@
+export * from "../test-support/process-helpers";
+export * from "../test-support/route-test-helpers";
+export * from "../test-support/test-helpers";