From 5a0702ecf828e82be5d9f608fd9ad4d2217083fa Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 29 Apr 2026 00:50:51 +0100
Subject: [PATCH] test: add reusable OpenClaw test instance helper

---
 docs/reference/test.md                      |   2 +-
 test/helpers/gateway-e2e-harness.ts         | 283 +------------
 test/helpers/openclaw-test-instance.test.ts |  58 +++
 test/helpers/openclaw-test-instance.ts      | 444 ++++++++++++++++++++
 4 files changed, 510 insertions(+), 277 deletions(-)
 create mode 100644 test/helpers/openclaw-test-instance.test.ts
 create mode 100644 test/helpers/openclaw-test-instance.ts

diff --git a/docs/reference/test.md b/docs/reference/test.md
index 07eb930204d..38bfe7a19a8 100644
--- a/docs/reference/test.md
+++ b/docs/reference/test.md
@@ -16,7 +16,7 @@ title: "Tests"
 - `pnpm check:changed`: runs the smart changed check gate for the diff against `origin/main`. It runs typecheck, lint, and guard commands for the affected architectural lanes, but does not run Vitest tests. Use `pnpm test:changed` or explicit `pnpm test <target>` for test proof.
 - `pnpm test`: routes explicit file/directory targets through scoped Vitest lanes. Untargeted runs use fixed shard groups and expand to leaf configs for local parallel execution; the extension group always expands to the per-extension shard configs instead of one giant root-project process.
 - Test wrapper runs end with a short `[test] passed|failed|skipped ... in ...` summary. Vitest's own duration line stays the per-shard detail.
-- Shared OpenClaw test state: use `src/test-utils/openclaw-test-state.ts` from Vitest when a test needs an isolated `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, config fixture, workspace, agent dir, or auth-profile store. Docker/Bash E2E lanes that source `scripts/lib/docker-e2e-image.sh` can pass `docker_e2e_test_state_shell_b64 <label> <scenario>` into the container and `eval` the decoded snippet there; multi-home scripts can pass `docker_e2e_test_state_function_b64` and call `openclaw_test_state_create <label> <scenario>` in each flow. Lower-level callers can use `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` for an in-container shell snippet, or `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` for a sourceable host env file. The `--` before `create` keeps newer Node runtimes from treating `--env-file` as a Node flag.
+- Shared OpenClaw test state: use `src/test-utils/openclaw-test-state.ts` from Vitest when a test needs an isolated `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, config fixture, workspace, agent dir, or auth-profile store. For process-level E2E tests that need a running Gateway, use `test/helpers/openclaw-test-instance.ts` so state, config, CLI env, gateway startup, log capture, and cleanup stay together. Docker/Bash E2E lanes that source `scripts/lib/docker-e2e-image.sh` can pass `docker_e2e_test_state_shell_b64 <label> <scenario>` into the container and `eval` the decoded snippet there; multi-home scripts can pass `docker_e2e_test_state_function_b64` and call `openclaw_test_state_create <label> <scenario>` in each flow. Lower-level callers can use `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` for an in-container shell snippet, or `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` for a sourceable host env file. The `--` before `create` keeps newer Node runtimes from treating `--env-file` as a Node flag.
 - Full, extension, and include-pattern shard runs update local timing data in `.artifacts/vitest-shard-timings.json`; later whole-config runs use those timings to balance slow and fast shards. Include-pattern CI shards append the shard name to the timing key, which keeps filtered shard timings visible without replacing whole-config timing data. Set `OPENCLAW_TEST_PROJECTS_TIMINGS=0` to ignore the local timing artifact.
 - Selected `plugin-sdk` and `commands` test files now route through dedicated light lanes that keep only `test/setup.ts`, leaving runtime-heavy cases on their existing lanes.
 - Source files with sibling tests map to that sibling before falling back to wider directory globs. Helper edits under `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers`, and `src/plugins/contracts` use a local import graph to run importing tests instead of broad-running every shard when the dependency path is precise.
diff --git a/test/helpers/gateway-e2e-harness.ts b/test/helpers/gateway-e2e-harness.ts
index bfbdfc1ed66..30c87e9cbf2 100644
--- a/test/helpers/gateway-e2e-harness.ts
+++ b/test/helpers/gateway-e2e-harness.ts
@@ -1,20 +1,13 @@
-import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import fs from "node:fs/promises";
 import { request as httpRequest } from "node:http";
-import net from "node:net";
-import os from "node:os";
 import path from "node:path";
-import {
-  BUILD_STAMP_FILE,
-  RUNTIME_POSTBUILD_STAMP_FILE,
-} from "../../scripts/lib/local-build-metadata-paths.mjs";
 import { GatewayClient } from "../../src/gateway/client.js";
 import { connectGatewayClient } from "../../src/gateway/test-helpers.e2e.js";
 import { loadOrCreateDeviceIdentity } from "../../src/infra/device-identity.js";
 import { extractFirstTextBlock } from "../../src/shared/chat-message-content.js";
 import { sleep } from "../../src/utils.js";
 import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../../src/utils/message-channel.js";
+import { createOpenClawTestInstance, type OpenClawTestInstance } from "./openclaw-test-instance.js";
 
 export { extractFirstTextBlock };
 
@@ -25,287 +18,25 @@ export type ChatEventPayload = {
   message?: unknown;
 };
 
-export type GatewayInstance = {
-  name: string;
-  port: number;
-  hookToken: string;
-  gatewayToken: string;
-  homeDir: string;
-  stateDir: string;
-  configPath: string;
-  child: ChildProcessWithoutNullStreams;
-  stdout: string[];
-  stderr: string[];
-};
+export type GatewayInstance = OpenClawTestInstance;
 
-const GATEWAY_START_TIMEOUT_MS = 60_000;
-const GATEWAY_STOP_TIMEOUT_MS = 1_500;
 const GATEWAY_CONNECT_STATUS_TIMEOUT_MS = 2_000;
 const GATEWAY_NODE_STATUS_TIMEOUT_MS = 4_000;
 const GATEWAY_NODE_STATUS_POLL_MS = 20;
-const GATEWAY_HOME_REMOVE_RETRIES = 5;
-const GATEWAY_HOME_REMOVE_RETRY_DELAY_MS = 100;
-const GATEWAY_ENTRYPOINT_PREPARE_TIMEOUT_MS = 120_000;
-
-let gatewayEntrypointPromise: Promise<string[]> | null = null;
-
-async function resolveBuiltGatewayEntrypoint(cwd: string): Promise<string[] | null> {
-  const buildStampPath = path.join(cwd, "dist", BUILD_STAMP_FILE);
-  const runtimePostBuildStampPath = path.join(cwd, "dist", RUNTIME_POSTBUILD_STAMP_FILE);
-  for (const entrypoint of ["dist/index.js", "dist/index.mjs"]) {
-    try {
-      await Promise.all([
-        fs.access(path.join(cwd, entrypoint)),
-        fs.access(buildStampPath),
-        fs.access(runtimePostBuildStampPath),
-      ]);
-      return [entrypoint];
-    } catch {
-      // try the next built entrypoint
-    }
-  }
-  return null;
-}
-
-async function prepareGatewayEntrypoint(cwd: string): Promise<string[]> {
-  const builtEntrypoint = await resolveBuiltGatewayEntrypoint(cwd);
-  if (builtEntrypoint) {
-    return builtEntrypoint;
-  }
-
-  const stdout: string[] = [];
-  const stderr: string[] = [];
-  const child = spawn("node", ["scripts/run-node.mjs", "--help"], {
-    cwd,
-    env: { ...process.env, VITEST: "1" },
-    stdio: ["ignore", "pipe", "pipe"],
-  });
-  child.stdout?.setEncoding("utf8");
-  child.stderr?.setEncoding("utf8");
-  child.stdout?.on("data", (d) => stdout.push(String(d)));
-  child.stderr?.on("data", (d) => stderr.push(String(d)));
-
-  const completed = await Promise.race([
-    new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve, reject) => {
-      child.once("error", reject);
-      child.once("exit", (code, signal) => resolve({ code, signal }));
-    }),
-    sleep(GATEWAY_ENTRYPOINT_PREPARE_TIMEOUT_MS).then(() => null),
-  ]);
-
-  if (completed === null) {
-    child.kill("SIGKILL");
-    throw new Error(
-      `timeout preparing gateway entrypoint\n--- stdout ---\n${stdout.join("")}\n--- stderr ---\n${stderr.join("")}`,
-    );
-  }
-  if (completed.code !== 0) {
-    throw new Error(
-      `failed preparing gateway entrypoint (code=${String(completed.code)} signal=${String(
-        completed.signal,
-      )})\n--- stdout ---\n${stdout.join("")}\n--- stderr ---\n${stderr.join("")}`,
-    );
-  }
-
-  return (await resolveBuiltGatewayEntrypoint(cwd)) ?? ["scripts/run-node.mjs"];
-}
-
-async function resolveGatewayEntrypoint(cwd: string): Promise<string[]> {
-  gatewayEntrypointPromise ??= prepareGatewayEntrypoint(cwd);
-  return await gatewayEntrypointPromise;
-}
-
-const getFreePort = async () => {
-  const srv = net.createServer();
-  await new Promise<void>((resolve) => srv.listen(0, "127.0.0.1", resolve));
-  const addr = srv.address();
-  if (!addr || typeof addr === "string") {
-    srv.close();
-    throw new Error("failed to bind ephemeral port");
-  }
-  await new Promise<void>((resolve) => srv.close(() => resolve()));
-  return addr.port;
-};
-
-async function waitForPortOpen(
-  proc: ChildProcessWithoutNullStreams,
-  chunksOut: string[],
-  chunksErr: string[],
-  port: number,
-  timeoutMs: number,
-) {
-  const startedAt = Date.now();
-  while (Date.now() - startedAt < timeoutMs) {
-    if (proc.exitCode !== null) {
-      const stdout = chunksOut.join("");
-      const stderr = chunksErr.join("");
-      throw new Error(
-        `gateway exited before listening (code=${String(proc.exitCode)} signal=${String(proc.signalCode)})\n` +
-          `--- stdout ---\n${stdout}\n--- stderr ---\n${stderr}`,
-      );
-    }
-
-    try {
-      await new Promise<void>((resolve, reject) => {
-        const socket = net.connect({ host: "127.0.0.1", port });
-        socket.once("connect", () => {
-          socket.destroy();
-          resolve();
-        });
-        socket.once("error", (err) => {
-          socket.destroy();
-          reject(err);
-        });
-      });
-      return;
-    } catch {
-      // keep polling
-    }
-
-    await sleep(10);
-  }
-  const stdout = chunksOut.join("");
-  const stderr = chunksErr.join("");
-  throw new Error(
-    `timeout waiting for gateway to listen on port ${port}\n` +
-      `--- stdout ---\n${stdout}\n--- stderr ---\n${stderr}`,
-  );
-}
-
-async function waitForGatewayExit(
-  child: ChildProcessWithoutNullStreams,
-  timeoutMs: number,
-): Promise<boolean> {
-  return await Promise.race([
-    new Promise<boolean>((resolve) => {
-      if (child.exitCode !== null || child.signalCode !== null) {
-        return resolve(true);
-      }
-      child.once("exit", () => resolve(true));
-    }),
-    sleep(timeoutMs).then(() => false),
-  ]);
-}
-
-async function removeGatewayHome(homeDir: string) {
-  await fs.rm(homeDir, {
-    recursive: true,
-    force: true,
-    maxRetries: GATEWAY_HOME_REMOVE_RETRIES,
-    retryDelay: GATEWAY_HOME_REMOVE_RETRY_DELAY_MS,
-  });
-}
 
 export async function spawnGatewayInstance(name: string): Promise<GatewayInstance> {
-  const port = await getFreePort();
-  const hookToken = `token-${name}-${randomUUID()}`;
-  const gatewayToken = `gateway-${name}-${randomUUID()}`;
-  const homeDir = await fs.mkdtemp(path.join(os.tmpdir(), `openclaw-e2e-${name}-`));
-  const configDir = path.join(homeDir, ".openclaw");
-  await fs.mkdir(configDir, { recursive: true });
-  const configPath = path.join(configDir, "openclaw.json");
-  const stateDir = path.join(configDir, "state");
-  const config = {
-    gateway: {
-      port,
-      auth: { mode: "token", token: gatewayToken },
-      controlUi: { enabled: false },
-    },
-    hooks: { enabled: true, token: hookToken, path: "/hooks" },
-  };
-  await fs.writeFile(configPath, JSON.stringify(config, null, 2), "utf8");
-
-  const stdout: string[] = [];
-  const stderr: string[] = [];
-  let child: ChildProcessWithoutNullStreams | null = null;
-
+  const inst = await createOpenClawTestInstance({ name });
   try {
-    const cwd = process.cwd();
-    const entrypoint = await resolveGatewayEntrypoint(cwd);
-    child = spawn(
-      "node",
-      [
-        ...entrypoint,
-        "gateway",
-        "--port",
-        String(port),
-        "--bind",
-        "loopback",
-        "--allow-unconfigured",
-      ],
-      {
-        cwd,
-        env: {
-          ...process.env,
-          HOME: homeDir,
-          OPENCLAW_CONFIG_PATH: configPath,
-          OPENCLAW_STATE_DIR: stateDir,
-          OPENCLAW_GATEWAY_TOKEN: "",
-          OPENCLAW_GATEWAY_PASSWORD: "",
-          OPENCLAW_SKIP_CHANNELS: "1",
-          OPENCLAW_SKIP_PROVIDERS: "1",
-          OPENCLAW_SKIP_GMAIL_WATCHER: "1",
-          OPENCLAW_SKIP_CRON: "1",
-          OPENCLAW_SKIP_BROWSER_CONTROL_SERVER: "1",
-          OPENCLAW_SKIP_CANVAS_HOST: "1",
-          OPENCLAW_TEST_MINIMAL_GATEWAY: "1",
-          VITEST: "1",
-        },
-        stdio: ["ignore", "pipe", "pipe"],
-      },
-    );
-
-    child.stdout?.setEncoding("utf8");
-    child.stderr?.setEncoding("utf8");
-    child.stdout?.on("data", (d) => stdout.push(String(d)));
-    child.stderr?.on("data", (d) => stderr.push(String(d)));
-
-    await waitForPortOpen(child, stdout, stderr, port, GATEWAY_START_TIMEOUT_MS);
-
-    return {
-      name,
-      port,
-      hookToken,
-      gatewayToken,
-      homeDir,
-      stateDir,
-      configPath,
-      child,
-      stdout,
-      stderr,
-    };
+    await inst.startGateway();
+    return inst;
   } catch (err) {
-    if (child && child.exitCode === null && !child.killed) {
-      try {
-        child.kill("SIGKILL");
-      } catch {
-        // ignore
-      }
-      await waitForGatewayExit(child, GATEWAY_STOP_TIMEOUT_MS);
-    }
-    await removeGatewayHome(homeDir);
+    await inst.cleanup();
     throw err;
   }
 }
 
 export async function stopGatewayInstance(inst: GatewayInstance) {
-  if (inst.child.exitCode === null && !inst.child.killed) {
-    try {
-      inst.child.kill("SIGTERM");
-    } catch {
-      // ignore
-    }
-  }
-  let exited = await waitForGatewayExit(inst.child, GATEWAY_STOP_TIMEOUT_MS);
-  if (!exited && inst.child.exitCode === null && !inst.child.killed) {
-    try {
-      inst.child.kill("SIGKILL");
-    } catch {
-      // ignore
-    }
-    await waitForGatewayExit(inst.child, GATEWAY_STOP_TIMEOUT_MS);
-  }
-  await removeGatewayHome(inst.homeDir);
+  await inst.cleanup();
 }
 
 export async function postJson(
diff --git a/test/helpers/openclaw-test-instance.test.ts b/test/helpers/openclaw-test-instance.test.ts
new file mode 100644
index 00000000000..6cbcaed945c
--- /dev/null
+++ b/test/helpers/openclaw-test-instance.test.ts
@@ -0,0 +1,58 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { createOpenClawTestInstance } from "./openclaw-test-instance.js";
+
+describe("openclaw test instance", () => {
+  it("creates isolated config and spawn env without mutating process env", async () => {
+    const previousHome = process.env.HOME;
+    const inst = await createOpenClawTestInstance({
+      name: "instance-unit",
+      gatewayToken: "gateway-token",
+      hookToken: "hook-token",
+      config: {
+        gateway: {
+          bind: "loopback",
+        },
+      },
+      env: {
+        OPENCLAW_SKIP_CRON: "0",
+      },
+    });
+
+    try {
+      expect(process.env.HOME).toBe(previousHome);
+      expect(inst.homeDir).toBe(path.join(inst.state.root, "home"));
+      expect(inst.stateDir).toBe(path.join(inst.homeDir, ".openclaw"));
+      expect(inst.configPath).toBe(path.join(inst.stateDir, "openclaw.json"));
+      expect(inst.env.HOME).toBe(inst.homeDir);
+      expect(inst.env.OPENCLAW_STATE_DIR).toBe(inst.stateDir);
+      expect(inst.env.OPENCLAW_CONFIG_PATH).toBe(inst.configPath);
+      expect(inst.env.OPENCLAW_SKIP_CRON).toBe("0");
+
+      const config = JSON.parse(await fs.readFile(inst.configPath, "utf8"));
+      expect(config).toMatchObject({
+        gateway: {
+          bind: "loopback",
+          port: inst.port,
+          auth: {
+            mode: "token",
+            token: "gateway-token",
+          },
+          controlUi: {
+            enabled: false,
+          },
+        },
+        hooks: {
+          enabled: true,
+          token: "hook-token",
+          path: "/hooks",
+        },
+      });
+    } finally {
+      await inst.cleanup();
+    }
+
+    await expect(fs.stat(inst.state.root)).rejects.toThrow();
+  });
+});
diff --git a/test/helpers/openclaw-test-instance.ts b/test/helpers/openclaw-test-instance.ts
new file mode 100644
index 00000000000..a9bd84fe6d9
--- /dev/null
+++ b/test/helpers/openclaw-test-instance.ts
@@ -0,0 +1,444 @@
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import net from "node:net";
+import path from "node:path";
+import {
+  BUILD_STAMP_FILE,
+  RUNTIME_POSTBUILD_STAMP_FILE,
+} from "../../scripts/lib/local-build-metadata-paths.mjs";
+import {
+  createOpenClawTestState,
+  type OpenClawTestState,
+  type OpenClawTestStateOptions,
+} from "../../src/test-utils/openclaw-test-state.js";
+import { sleep } from "../../src/utils.js";
+
+export type OpenClawTestInstanceOptions = {
+  name: string;
+  cwd?: string;
+  port?: number;
+  gatewayToken?: string;
+  hookToken?: string;
+  config?: Record<string, unknown>;
+  env?: Record<string, string | undefined>;
+  state?: Omit<OpenClawTestStateOptions, "applyEnv" | "gateway" | "env">;
+  gatewayArgs?: string[];
+  startTimeoutMs?: number;
+  stopTimeoutMs?: number;
+};
+
+export type OpenClawTestInstanceCommandResult = {
+  code: number | null;
+  signal: NodeJS.Signals | null;
+  stdout: string;
+  stderr: string;
+};
+
+export type OpenClawTestInstance = {
+  name: string;
+  port: number;
+  url: string;
+  hookToken: string;
+  gatewayToken: string;
+  homeDir: string;
+  stateDir: string;
+  configPath: string;
+  state: OpenClawTestState;
+  stdout: string[];
+  stderr: string[];
+  child?: ChildProcessWithoutNullStreams;
+  env: NodeJS.ProcessEnv;
+  entrypoint: () => Promise<string[]>;
+  cli: (
+    args: string[],
+    options?: { timeoutMs?: number },
+  ) => Promise<OpenClawTestInstanceCommandResult>;
+  startGateway: () => Promise<void>;
+  stopGateway: () => Promise<void>;
+  logs: () => string;
+  cleanup: () => Promise<void>;
+};
+
+const GATEWAY_START_TIMEOUT_MS = 60_000;
+const GATEWAY_STOP_TIMEOUT_MS = 1_500;
+const GATEWAY_ENTRYPOINT_PREPARE_TIMEOUT_MS = 120_000;
+const COMMAND_TIMEOUT_MS = 30_000;
+const entrypointPromises = new Map<string, Promise<string[]>>();
+
+async function resolveBuiltGatewayEntrypoint(cwd: string): Promise<string[] | null> {
+  const buildStampPath = path.join(cwd, "dist", BUILD_STAMP_FILE);
+  const runtimePostBuildStampPath = path.join(cwd, "dist", RUNTIME_POSTBUILD_STAMP_FILE);
+  for (const entrypoint of ["dist/index.js", "dist/index.mjs"]) {
+    try {
+      await Promise.all([
+        fs.access(path.join(cwd, entrypoint)),
+        fs.access(buildStampPath),
+        fs.access(runtimePostBuildStampPath),
+      ]);
+      return [entrypoint];
+    } catch {
+      // try the next built entrypoint
+    }
+  }
+  return null;
+}
+
+async function prepareGatewayEntrypoint(cwd: string): Promise<string[]> {
+  const builtEntrypoint = await resolveBuiltGatewayEntrypoint(cwd);
+  if (builtEntrypoint) {
+    return builtEntrypoint;
+  }
+
+  const stdout: string[] = [];
+  const stderr: string[] = [];
+  const child = spawn("node", ["scripts/run-node.mjs", "--help"], {
+    cwd,
+    env: { ...process.env, VITEST: "1" },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  child.stdout?.setEncoding("utf8");
+  child.stderr?.setEncoding("utf8");
+  child.stdout?.on("data", (d) => stdout.push(String(d)));
+  child.stderr?.on("data", (d) => stderr.push(String(d)));
+
+  const completed = await Promise.race([
+    new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve, reject) => {
+      child.once("error", reject);
+      child.once("exit", (code, signal) => resolve({ code, signal }));
+    }),
+    sleep(GATEWAY_ENTRYPOINT_PREPARE_TIMEOUT_MS).then(() => null),
+  ]);
+
+  if (completed === null) {
+    child.kill("SIGKILL");
+    throw new Error(
+      `timeout preparing gateway entrypoint\n--- stdout ---\n${stdout.join("")}\n--- stderr ---\n${stderr.join("")}`,
+    );
+  }
+  if (completed.code !== 0) {
+    throw new Error(
+      `failed preparing gateway entrypoint (code=${String(completed.code)} signal=${String(
+        completed.signal,
+      )})\n--- stdout ---\n${stdout.join("")}\n--- stderr ---\n${stderr.join("")}`,
+    );
+  }
+
+  return (await resolveBuiltGatewayEntrypoint(cwd)) ?? ["scripts/run-node.mjs"];
+}
+
+async function resolveGatewayEntrypoint(cwd: string): Promise<string[]> {
+  let promise = entrypointPromises.get(cwd);
+  if (!promise) {
+    promise = prepareGatewayEntrypoint(cwd);
+    entrypointPromises.set(cwd, promise);
+  }
+  return await promise;
+}
+
+const getFreePort = async () => {
+  const srv = net.createServer();
+  await new Promise<void>((resolve) => srv.listen(0, "127.0.0.1", resolve));
+  const addr = srv.address();
+  if (!addr || typeof addr === "string") {
+    srv.close();
+    throw new Error("failed to bind ephemeral port");
+  }
+  await new Promise<void>((resolve) => srv.close(() => resolve()));
+  return addr.port;
+};
+
+async function waitForPortOpen(
+  proc: ChildProcessWithoutNullStreams,
+  chunksOut: string[],
+  chunksErr: string[],
+  port: number,
+  timeoutMs: number,
+) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (proc.exitCode !== null) {
+      throw new Error(
+        `gateway exited before listening (code=${String(proc.exitCode)} signal=${String(
+          proc.signalCode,
+        )})\n${formatLogs(chunksOut, chunksErr)}`,
+      );
+    }
+
+    try {
+      await new Promise<void>((resolve, reject) => {
+        const socket = net.connect({ host: "127.0.0.1", port });
+        socket.once("connect", () => {
+          socket.destroy();
+          resolve();
+        });
+        socket.once("error", (err) => {
+          socket.destroy();
+          reject(err);
+        });
+      });
+      return;
+    } catch {
+      // keep polling
+    }
+
+    await sleep(10);
+  }
+  throw new Error(
+    `timeout waiting for gateway to listen on port ${port}\n${formatLogs(chunksOut, chunksErr)}`,
+  );
+}
+
+async function waitForGatewayExit(
+  child: ChildProcessWithoutNullStreams,
+  timeoutMs: number,
+): Promise<boolean> {
+  return await Promise.race([
+    new Promise<boolean>((resolve) => {
+      if (child.exitCode !== null || child.signalCode !== null) {
+        return resolve(true);
+      }
+      child.once("exit", () => resolve(true));
+    }),
+    sleep(timeoutMs).then(() => false),
+  ]);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function mergeConfig(
+  base: Record<string, unknown>,
+  override: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  if (!override) {
+    return base;
+  }
+  const result: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    const existing = result[key];
+    result[key] = isRecord(existing) && isRecord(value) ? mergeConfig(existing, value) : value;
+  }
+  return result;
+}
+
+function formatLogs(stdout: string[], stderr: string[]): string {
+  return `--- stdout ---\n${stdout.join("")}\n--- stderr ---\n${stderr.join("")}`;
+}
+
+function createInstanceEnv(params: {
+  stateEnv: NodeJS.ProcessEnv;
+  extraEnv: Record<string, string | undefined>;
+}): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {
+    ...params.stateEnv,
+    OPENCLAW_GATEWAY_TOKEN: "",
+    OPENCLAW_GATEWAY_PASSWORD: "",
+    OPENCLAW_SKIP_CHANNELS: "1",
+    OPENCLAW_SKIP_PROVIDERS: "1",
+    OPENCLAW_SKIP_GMAIL_WATCHER: "1",
+    OPENCLAW_SKIP_CRON: "1",
+    OPENCLAW_SKIP_BROWSER_CONTROL_SERVER: "1",
+    OPENCLAW_SKIP_CANVAS_HOST: "1",
+    OPENCLAW_TEST_MINIMAL_GATEWAY: "1",
+    VITEST: "1",
+  };
+  for (const [key, value] of Object.entries(params.extraEnv)) {
+    if (value === undefined) {
+      delete env[key];
+    } else {
+      env[key] = value;
+    }
+  }
+  return env;
+}
+
+export async function createOpenClawTestInstance(
+  options: OpenClawTestInstanceOptions,
+): Promise<OpenClawTestInstance> {
+  const cwd = options.cwd ?? process.cwd();
+  const port = options.port ?? (await getFreePort());
+  const gatewayToken = options.gatewayToken ?? `gateway-${options.name}-${randomUUID()}`;
+  const hookToken = options.hookToken ?? `token-${options.name}-${randomUUID()}`;
+  const state = await createOpenClawTestState({
+    label: options.name,
+    layout: "home",
+    ...options.state,
+    applyEnv: false,
+    env: options.env,
+  });
+  await state.writeConfig(
+    mergeConfig(
+      {
+        gateway: {
+          port,
+          auth: { mode: "token", token: gatewayToken },
+          controlUi: { enabled: false },
+        },
+        hooks: { enabled: true, token: hookToken, path: "/hooks" },
+      },
+      options.config,
+    ),
+  );
+
+  const stdout: string[] = [];
+  const stderr: string[] = [];
+  const env = createInstanceEnv({
+    stateEnv: state.env,
+    extraEnv: options.env ?? {},
+  });
+  let child: ChildProcessWithoutNullStreams | undefined;
+  let cleaned = false;
+
+  const instance: OpenClawTestInstance = {
+    name: options.name,
+    port,
+    url: `ws://127.0.0.1:${port}`,
+    hookToken,
+    gatewayToken,
+    homeDir: state.home,
+    stateDir: state.stateDir,
+    configPath: state.configPath,
+    state,
+    stdout,
+    stderr,
+    get child() {
+      return child;
+    },
+    env,
+    entrypoint: () => resolveGatewayEntrypoint(cwd),
+    cli: async (args, commandOptions = {}) => {
+      const entrypoint = await resolveGatewayEntrypoint(cwd);
+      return await runCommand({
+        args: ["node", ...entrypoint, ...args],
+        cwd,
+        env,
+        timeoutMs: commandOptions.timeoutMs ?? COMMAND_TIMEOUT_MS,
+      });
+    },
+    startGateway: async () => {
+      if (child && child.exitCode === null && !child.killed) {
+        return;
+      }
+      const entrypoint = await resolveGatewayEntrypoint(cwd);
+      child = spawn(
+        "node",
+        [
+          ...entrypoint,
+          "gateway",
+          "--port",
+          String(port),
+          "--bind",
+          "loopback",
+          "--allow-unconfigured",
+          ...(options.gatewayArgs ?? []),
+        ],
+        {
+          cwd,
+          env,
+          stdio: ["ignore", "pipe", "pipe"],
+        },
+      );
+
+      child.stdout?.setEncoding("utf8");
+      child.stderr?.setEncoding("utf8");
+      child.stdout?.on("data", (d) => stdout.push(String(d)));
+      child.stderr?.on("data", (d) => stderr.push(String(d)));
+
+      try {
+        await waitForPortOpen(
+          child,
+          stdout,
+          stderr,
+          port,
+          options.startTimeoutMs ?? GATEWAY_START_TIMEOUT_MS,
+        );
+      } catch (err) {
+        await instance.stopGateway();
+        throw err;
+      }
+    },
+    stopGateway: async () => {
+      if (!child) {
+        return;
+      }
+      if (child.exitCode === null && !child.killed) {
+        try {
+          child.kill("SIGTERM");
+        } catch {
+          // ignore
+        }
+      }
+      let exited = await waitForGatewayExit(
+        child,
+        options.stopTimeoutMs ?? GATEWAY_STOP_TIMEOUT_MS,
+      );
+      if (!exited && child.exitCode === null && !child.killed) {
+        try {
+          child.kill("SIGKILL");
+        } catch {
+          // ignore
+        }
+        exited = await waitForGatewayExit(child, options.stopTimeoutMs ?? GATEWAY_STOP_TIMEOUT_MS);
+      }
+      if (exited) {
+        child = undefined;
+      }
+    },
+    logs: () => formatLogs(stdout, stderr),
+    cleanup: async () => {
+      if (cleaned) {
+        return;
+      }
+      cleaned = true;
+      await instance.stopGateway();
+      await state.cleanup();
+    },
+  };
+
+  return instance;
+}
+
+async function runCommand(params: {
+  args: string[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  timeoutMs: number;
+}): Promise<OpenClawTestInstanceCommandResult> {
+  const [command, ...args] = params.args;
+  if (!command) {
+    throw new Error("missing command");
+  }
+  const stdout: string[] = [];
+  const stderr: string[] = [];
+  const child = spawn(command, args, {
+    cwd: params.cwd,
+    env: params.env,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  child.stdout?.setEncoding("utf8");
+  child.stderr?.setEncoding("utf8");
+  child.stdout?.on("data", (d) => stdout.push(String(d)));
+  child.stderr?.on("data", (d) => stderr.push(String(d)));
+
+  const completed = await Promise.race([
+    new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve, reject) => {
+      child.once("error", reject);
+      child.once("exit", (code, signal) => resolve({ code, signal }));
+    }),
+    sleep(params.timeoutMs).then(() => null),
+  ]);
+  if (completed === null) {
+    child.kill("SIGKILL");
+    await waitForGatewayExit(child, GATEWAY_STOP_TIMEOUT_MS);
+    throw new Error(
+      `command timed out after ${params.timeoutMs}ms: ${params.args.join(" ")}\n${formatLogs(stdout, stderr)}`,
+    );
+  }
+  return {
+    ...completed,
+    stdout: stdout.join(""),
+    stderr: stderr.join(""),
+  };
+}