π OpenHands: AI-Driven Development
// @vitest-environment node
// These tests load `scripts/dev-with-automation.mjs` and `scripts/dev-safe.mjs`,
// which construct file:// URLs relative to their own location via
// `new URL("../tools", import.meta.url)`. jsdom's URL constructor ignores
// file:// base URLs (it falls back to its document base, e.g.
// http://localhost:3000/), breaking that resolution; the Node environment
// has the standard WHATWG URL behavior that honors the file:// base.
import net from "node:net";
import { spawn, spawnSync } from "node:child_process";
import { once } from "node:events";
import {
existsSync,
mkdirSync,
mkdtempSync,
rmSync,
writeFileSync,
} from "node:fs";
import { homedir, tmpdir } from "node:os";
import path from "node:path";
import { setTimeout as delay } from "node:timers/promises";
import { fileURLToPath, pathToFileURL } from "node:url";
import { describe, expect, it, afterEach } from "vitest";
import {
buildAgentServerAutomationEnv,
buildAutomationCommand,
buildAutomationLogArgs,
buildAutomationTelemetryEnv,
buildAutomationRuntimeServicesInfo,
buildConfig,
buildRouteArgs,
buildViteBackendEnv,
buildViteFrontendEnv,
getAgentServerBaseUrl,
getFrontendBackend,
getLocalServiceRoutes,
getRejectPrefixes,
setServiceLogListener,
spawnService,
validateLocalAutomationPath,
DEFAULT_AUTOMATION_REPO,
DEFAULT_AUTOMATION_PACKAGE,
DEFAULT_AUTOMATION_VERSION,
buildMarsWebEnv,
} from "../../scripts/dev-with-automation.mjs";
import {
buildAgentServerEnv,
buildBackendLogEnv,
buildSafeDevConfig,
resetPersistedSessionApiKeyCache,
uvicornLogLevel,
} from "../../scripts/dev-safe.mjs";
import { createRouter } from "../../scripts/proxy-utils.mjs";
const repoRoot = path.resolve(
path.dirname(fileURLToPath(import.meta.url)),
"../..",
);
type RuntimeServicesInfo = {
services: Record<string, { url_from_agent: string }>;
};
describe("buildAutomationRuntimeServicesInfo", () => {
const config = {
mode: "agent-canvas",
agentServerPort: 18000,
ingressPort: 8000,
vitePort: 3001,
autoBackendPort: 18001,
launchFrontend: true,
launchAutomation: true,
};
it("advertises host services through the Docker host gateway", () => {
const info = buildAutomationRuntimeServicesInfo(config, {
OH_CONVERSATION_RUNTIME: "docker",
}) as RuntimeServicesInfo;
expect(info.services.agent_server.url_from_agent).toBe(
"http://localhost:18000",
);
expect(info.services.ingress.url_from_agent).toBe(
"http://host.docker.internal:8000",
);
expect(info.services.automation.url_from_agent).toBe(
"http://host.docker.internal:8000",
);
});
it("keeps host services on localhost for local conversations", () => {
const info = buildAutomationRuntimeServicesInfo(
config,
{},
) as RuntimeServicesInfo;
expect(info.services.ingress.url_from_agent).toBe("http://localhost:8000");
expect(info.services.automation.url_from_agent).toBe(
"http://localhost:18001",
);
});
});
describe("buildAutomationCommand", () => {
it("uses released PyPI version by default", () => {
const cmd = buildAutomationCommand({});
expect(cmd.command).toBe("uvx");
expect(cmd.args).toContain("--from");
expect(cmd.args).toContain(
`${DEFAULT_AUTOMATION_PACKAGE}==${DEFAULT_AUTOMATION_VERSION}`,
);
expect(cmd.args).toContain("uvicorn");
expect(cmd.args).toContain("openhands.automation.app:app");
expect(cmd.source).toBe(`PyPI (${DEFAULT_AUTOMATION_VERSION}, default)`);
});
it("requests the shared Python range for uvx in every source mode", () => {
// See buildUvxPythonArgs in dev-safe.mjs and #18654.
const variants = [
{},
{ OH_AUTOMATION_VERSION: "1.0.0" },
{ OH_AUTOMATION_GIT_REF: "main" },
];
for (const env of variants) {
const { command, args } = buildAutomationCommand(env);
expect(command).toBe("uvx");
expect(args.slice(0, 2)).toEqual(["--python", ">=3.12,<3.15"]);
}
});
it("leaves the interpreter choice to uv when UV_PYTHON is set", () => {
const { args } = buildAutomationCommand({ UV_PYTHON: "3.13" });
expect(args).not.toContain("--python");
});
it("uses custom git ref from OH_AUTOMATION_GIT_REF", () => {
const cmd = buildAutomationCommand({
OH_AUTOMATION_GIT_REF: "feat/my-feature",
});
expect(cmd.command).toBe("uvx");
expect(cmd.args).toContain("--from");
expect(cmd.args).toContain(
`git+${DEFAULT_AUTOMATION_REPO}@feat/my-feature`,
);
expect(cmd.source).toBe("git (feat/my-feature)");
});
it("uses custom repo with git ref", () => {
const cmd = buildAutomationCommand({
OH_AUTOMATION_REPO: "https://github.com/MyOrg/my-automation",
OH_AUTOMATION_GIT_REF: "main",
});
expect(cmd.command).toBe("uvx");
expect(cmd.args).toContain(
"git+https://github.com/MyOrg/my-automation@main",
);
});
it("uses both custom repo and ref together", () => {
const cmd = buildAutomationCommand({
OH_AUTOMATION_REPO: "https://github.com/MyOrg/my-automation",
OH_AUTOMATION_GIT_REF: "v1.0.0",
});
expect(cmd.command).toBe("uvx");
expect(cmd.args).toContain(
"git+https://github.com/MyOrg/[email protected]",
);
expect(cmd.source).toBe("git (v1.0.0)");
});
it("supports commit SHA as git ref", () => {
const cmd = buildAutomationCommand({
OH_AUTOMATION_GIT_REF: "abc123def456",
});
expect(cmd.command).toBe("uvx");
expect(cmd.args).toContain(`git+${DEFAULT_AUTOMATION_REPO}@abc123def456`);
expect(cmd.source).toBe("git (abc123def456)");
});
it("uses specific PyPI version when OH_AUTOMATION_VERSION is set", () => {
const cmd = buildAutomationCommand({
OH_AUTOMATION_VERSION: "1.0.0",
});
expect(cmd.command).toBe("uvx");
expect(cmd.args).toContain(`${DEFAULT_AUTOMATION_PACKAGE}==1.0.0`);
expect(cmd.source).toBe("PyPI (1.0.0)");
});
it("git ref takes precedence over version", () => {
const cmd = buildAutomationCommand({
OH_AUTOMATION_GIT_REF: "main",
OH_AUTOMATION_VERSION: "1.0.0",
});
expect(cmd.command).toBe("uvx");
expect(cmd.args).toContain(`git+${DEFAULT_AUTOMATION_REPO}@main`);
expect(cmd.args).not.toContain(`${DEFAULT_AUTOMATION_PACKAGE}==1.0.0`);
expect(cmd.source).toBe("git (main)");
});
it("runs a local checkout in place, ahead of the other env vars", () => {
const cmd = buildAutomationCommand({
OH_AUTOMATION_LOCAL_PATH: "/checkouts/automation",
OH_AUTOMATION_GIT_REF: "main",
OH_AUTOMATION_VERSION: "1.0.0",
});
expect(cmd.command).toBe("uv");
expect(cmd.args).toEqual([
"run",
"--project",
"/checkouts/automation",
"uvicorn",
"openhands.automation.app:app",
]);
expect(cmd.source).toBe("local (/checkouts/automation)");
});
});
describe("validateLocalAutomationPath", () => {
const dirs: string[] = [];
afterEach(() => {
while (dirs.length > 0) {
const dir = dirs.pop();
if (dir) rmSync(dir, { recursive: true, force: true });
}
});
function makeCheckout({ withProjectFile = true } = {}) {
const dir = mkdtempSync(path.join(tmpdir(), "automation-checkout-"));
dirs.push(dir);
if (withProjectFile) {
writeFileSync(path.join(dir, "pyproject.toml"), "[project]\n");
}
return dir;
}
it("accepts an absolute path to a Python project", () => {
expect(() => validateLocalAutomationPath(makeCheckout())).not.toThrow();
});
// Without these, `uv run --project <bad path>` just exits and the rest of
// the stack stays up, leaving the automations UI blaming the backend.
it("rejects a relative path", () => {
expect(() => validateLocalAutomationPath("../automation")).toThrow(
/absolute path/i,
);
});
it("rejects a path that does not exist", () => {
const dir = makeCheckout();
rmSync(dir, { recursive: true, force: true });
expect(() => validateLocalAutomationPath(dir)).toThrow(/does not exist/i);
});
it("rejects a directory that is not a Python project", () => {
expect(() =>
validateLocalAutomationPath(makeCheckout({ withProjectFile: false })),
).toThrow(/pyproject\.toml/);
});
});
describe("buildAgentServerAutomationEnv", () => {
it("exposes the session API key as OPENHANDS_AUTOMATION_API_KEY for agent curl commands", () => {
expect(
buildAgentServerAutomationEnv({ sessionApiKey: "shared-session-key" }),
).toEqual({
OPENHANDS_AUTOMATION_API_KEY: "shared-session-key",
});
});
});
describe("buildAutomationTelemetryEnv", () => {
it("provides the shared frontend PostHog key to automation by default", () => {
expect(buildAutomationTelemetryEnv({})).toEqual({
AUTOMATION_POSTHOG_API_KEY:
"phc_kBtz5nKmxVRRQ7HtPwr2QX9eMC5j65zE86QKocVNwb4U",
AUTOMATION_POSTHOG_HOST: "https://us.i.posthog.com",
});
});
it("prefers explicit automation telemetry settings", () => {
expect(
buildAutomationTelemetryEnv({
AUTOMATION_POSTHOG_API_KEY: "phc_auto",
AUTOMATION_POSTHOG_HOST: "https://auto.example",
VITE_POSTHOG_API_KEY: "phc_frontend",
VITE_POSTHOG_HOST: "https://frontend.example",
}),
).toEqual({
AUTOMATION_POSTHOG_API_KEY: "phc_auto",
AUTOMATION_POSTHOG_HOST: "https://auto.example",
});
});
it("uses explicit frontend telemetry settings when automation settings are absent", () => {
expect(
buildAutomationTelemetryEnv({
VITE_POSTHOG_API_KEY: "phc_frontend",
VITE_POSTHOG_HOST: "https://frontend.example",
}),
).toEqual({
AUTOMATION_POSTHOG_API_KEY: "phc_frontend",
AUTOMATION_POSTHOG_HOST: "https://frontend.example",
});
});
it("does not default automation telemetry when do-not-track is enabled", () => {
expect(buildAutomationTelemetryEnv({ VITE_DO_NOT_TRACK: "1" })).toEqual({});
});
});
describe("buildConfig", () => {
const servers: net.Server[] = [];
const keyDirs: string[] = [];
afterEach(() => {
for (const server of servers) {
server.close();
}
servers.length = 0;
while (keyDirs.length > 0) {
const dir = keyDirs.pop();
if (dir) rmSync(dir, { recursive: true, force: true });
}
resetPersistedSessionApiKeyCache();
});
/**
* Build an env that points persisted dev API key files at a fresh temp dir,
* so tests don't write to the user's real ~/.openhands/agent-canvas files.
*
* Also redirects all service ports to high port numbers so that buildConfig's
* assertPortsFree check passes even when a real dev stack is running on the
* default ports (18000, 18001, 3001, 8000).
*/
function envWithIsolatedKeyPath(
extra: Record<string, string> = {},
): Record<string, string> {
const dir = mkdtempSync(path.join(tmpdir(), "buildconfig-key-"));
keyDirs.push(dir);
return {
OH_SESSION_API_KEY_PATH: path.join(dir, "session-api-key.txt"),
// High ports that are almost certainly free, so assertPortsFree passes.
PORT: "19902",
OH_CANVAS_SAFE_BACKEND_PORT: "19900",
OH_CANVAS_SAFE_AUTOMATION_PORT: "19901",
OH_CANVAS_SAFE_VITE_PORT: "19903",
...extra,
};
}
// Exercise the public launcher entry point through its existing embedder
// prerequisite callback. Stop before services start; no test-only exports.
function launchDirectoryProbe(env: Record<string, string>, args: string[]) {
const probeHome = path.dirname(env.OH_SESSION_API_KEY_PATH);
const script = `
import { main } from ${JSON.stringify(pathToFileURL(path.join(repoRoot, "scripts/dev-with-automation.mjs")).href)};
process.argv = [process.execPath, "directory-probe", ...${JSON.stringify(args)}];
try {
await main({
staticMode: true,
skipNpmCheck: true,
extraPrereqs(config) {
console.log("QA_DIRECTORY_PROBE=" + JSON.stringify({ stateDir: config.stateDir, tmuxTmpDir: config.tmuxTmpDir }));
throw new Error("qa-directory-probe-complete");
},
});
} catch (error) {
if (error.message !== "qa-directory-probe-complete") throw error;
}
`;
// Only command discovery is stubbed. No backend executes in this probe.
if (process.platform === "win32") {
writeFileSync(path.join(probeHome, "uvx.cmd"), "@exit /b 0\r\n");
} else {
writeFileSync(path.join(probeHome, "uvx"), "#!/bin/sh\nexit 0\n", {
mode: 0o700,
});
}
// An ambient TMUX_TMPDIR (e.g. npm test run inside tmux) would mask the
// default; only the case's own env may set it.
const { TMUX_TMPDIR: _ambientTmuxTmpDir, ...parentEnv } = process.env;
const result = spawnSync(
process.execPath,
["--input-type=module", "-e", script],
{
env: {
...parentEnv,
...env,
HOME: probeHome,
PATH: `${probeHome}${path.delimiter}${process.env.PATH ?? ""}`,
OH_AGENT_SERVER_LOCAL_PATH: "",
OH_AUTOMATION_LOCAL_PATH: "",
},
encoding: "utf8",
timeout: 15_000,
},
);
expect(result.status, result.stderr).toBe(0);
const line = result.stdout
.split("\n")
.find((item) => item.startsWith("QA_DIRECTORY_PROBE="));
expect(line, result.stdout).toBeDefined();
return JSON.parse(line!.slice("QA_DIRECTORY_PROBE=".length));
}
it("builds default config with correct ports", async () => {
const config = await buildConfig({}, envWithIsolatedKeyPath());
// Ports should be allocated (either defaults if free, or alternatives)
expect(typeof config.ingressPort).toBe("number");
expect(config.ingressPort).toBeGreaterThan(0);
expect(typeof config.agentServerPort).toBe("number");
expect(config.agentServerPort).toBeGreaterThan(0);
expect(typeof config.autoBackendPort).toBe("number");
expect(config.autoBackendPort).toBeGreaterThan(0);
expect(typeof config.vitePort).toBe("number");
expect(config.vitePort).toBeGreaterThan(0);
expect(config.vscodePort).toBe(config.agentServerPort + 1000);
// All four main ports should be unique
const ports = new Set([
config.ingressPort,
config.agentServerPort,
config.autoBackendPort,
config.vitePort,
]);
expect(ports.size).toBe(4);
});
it("creates separate default tmux directories before local backends start", async () => {
const configs = [];
for (let n = 0; n < 2; n += 1) {
const env = envWithIsolatedKeyPath();
env.OH_CANVAS_SAFE_STATE_DIR = path.join(
path.dirname(env.OH_SESSION_API_KEY_PATH),
"state",
);
const config = launchDirectoryProbe(env, ["--backend-only"]);
const expected = path.join(config.stateDir, "tmux");
expect(config.tmuxTmpDir).toBe(expected);
expect(existsSync(expected)).toBe(true);
configs.push(config);
}
expect(configs[0].tmuxTmpDir).not.toBe(configs[1].tmuxTmpDir);
});
it("creates and preserves an explicit socket-capable TMUX_TMPDIR", async () => {
const env = envWithIsolatedKeyPath();
env.OH_CANVAS_SAFE_STATE_DIR = path.join(
path.dirname(env.OH_SESSION_API_KEY_PATH),
"state",
);
env.TMUX_TMPDIR = path.join(
path.dirname(env.OH_SESSION_API_KEY_PATH),
"sockets",
);
const config = launchDirectoryProbe(env, ["--backend-only"]);
expect(config.tmuxTmpDir).toBe(env.TMUX_TMPDIR);
expect(existsSync(env.TMUX_TMPDIR)).toBe(true);
expect(existsSync(path.join(config.stateDir, "tmux"))).toBe(false);
});
it("does not create a local terminal directory in frontend-only mode", async () => {
const env = envWithIsolatedKeyPath();
env.OH_CANVAS_SAFE_STATE_DIR = path.join(
path.dirname(env.OH_SESSION_API_KEY_PATH),
"state",
);
const config = launchDirectoryProbe(env, ["--frontend-only"]);
expect(existsSync(path.join(config.stateDir, "tmux"))).toBe(false);
});
it("lets --automation-git-ref win over an exported OH_AUTOMATION_LOCAL_PATH", async () => {
// Otherwise someone with the checkout exported in their shell profile
// reproduces a bug against their own working tree while believing they
// are testing the ref they just passed.
const env = envWithIsolatedKeyPath({
OH_AUTOMATION_LOCAL_PATH: "/checkouts/automation",
});
await buildConfig({ automationGitRef: "abc123" }, env);
expect(env.OH_AUTOMATION_GIT_REF).toBe("abc123");
expect(env.OH_AUTOMATION_LOCAL_PATH).toBeUndefined();
expect(buildAutomationCommand(env).source).toBe("git (abc123)");
});
it("keeps a local checkout when no ref is passed", async () => {
const env = envWithIsolatedKeyPath({
OH_AUTOMATION_LOCAL_PATH: "/checkouts/automation",
});
await buildConfig({}, env);
expect(env.OH_AUTOMATION_LOCAL_PATH).toBe("/checkouts/automation");
});
it("respects preferred port from args when available", async () => {
// Use a high port unlikely to be busy
const preferredPort = 19500;
const config = await buildConfig(
{ port: preferredPort },
envWithIsolatedKeyPath(),
);
expect(config.ingressPort).toBe(preferredPort);
});
it("throws when ingress port is busy", async () => {
const server = net.createServer();
const busyPort = await new Promise<number>((resolve, reject) => {
server.listen(0, "127.0.0.1", () => {
const address = server.address();
if (!address || typeof address === "string") {
reject(new Error("Expected a TCP server address"));
return;
}
servers.push(server);
resolve(address.port);
});
server.on("error", reject);
});
await expect(
buildConfig({ port: busyPort }, envWithIsolatedKeyPath()),
).rejects.toThrow(new RegExp(`ingress.*port ${busyPort}`, "i"));
});
it("allocates valid ports for all services", async () => {
const config = await buildConfig({}, envWithIsolatedKeyPath());
// All service ports should be valid
expect(config.agentServerPort).toBeGreaterThan(0);
expect(config.autoBackendPort).toBeGreaterThan(0);
expect(config.vitePort).toBeGreaterThan(0);
expect(config.vscodePort).toBeGreaterThan(0);
// All service ports should be different from each other
const servicePorts = [
config.agentServerPort,
config.autoBackendPort,
config.vitePort,
config.ingressPort,
];
expect(new Set(servicePorts).size).toBe(servicePorts.length);
});
it("respects preferred PORT from env when available", async () => {
// Use a high port unlikely to be busy
const preferredPort = "19501";
const config = await buildConfig(
{},
envWithIsolatedKeyPath({ PORT: preferredPort }),
);
expect(config.ingressPort).toBe(19501);
});
it("args.port takes precedence over env.PORT", async () => {
// Use high ports unlikely to be busy
const config = await buildConfig(
{ port: 19502 },
envWithIsolatedKeyPath({ PORT: "19599" }),
);
expect(config.ingressPort).toBe(19502);
});
it("applies automationGitRef from args to env", async () => {
const env = envWithIsolatedKeyPath();
await buildConfig({ automationGitRef: "my-branch" }, env);
expect(env.OH_AUTOMATION_GIT_REF).toBe("my-branch");
});
it("applies automationRepo from args to env", async () => {
const env = envWithIsolatedKeyPath();
await buildConfig({ automationRepo: "https://example.com/repo" }, env);
expect(env.OH_AUTOMATION_REPO).toBe("https://example.com/repo");
});
it("uses correct state directory path", async () => {
const config = await buildConfig({}, envWithIsolatedKeyPath());
expect(config.stateDir).toBe(
path.join(homedir(), ".openhands", "agent-canvas"),
);
});
it("passes verbose flag through", async () => {
const config = await buildConfig(
{ verbose: true },
envWithIsolatedKeyPath(),
);
expect(config.verbose).toBe(true);
});
it("sessionApiKey is a 64-char hex string by default", async () => {
const config = await buildConfig({}, envWithIsolatedKeyPath());
expect(config.sessionApiKey).toMatch(/^[0-9a-f]{64}$/);
});
it("falls back to a freshly persisted session API key by default", async () => {
const config = await buildConfig({}, envWithIsolatedKeyPath());
// Default is a 64-char hex string (256-bit random key) read from /
// written to OH_SESSION_API_KEY_PATH.
expect(config.sessionApiKey).toMatch(/^[0-9a-f]{64}$/);
});
it("reuses the persisted session API key across calls (stable across restarts)", async () => {
const env = envWithIsolatedKeyPath();
const first = await buildConfig({}, env);
// Simulate a fresh process invocation (the file on disk should be
// what makes the key stable).
resetPersistedSessionApiKeyCache();
const second = await buildConfig({}, env);
expect(second.sessionApiKey).toBe(first.sessionApiKey);
});
it("reads sessionApiKey from LOCAL_BACKEND_API_KEY", async () => {
const config = await buildConfig(
{},
{ ...envWithIsolatedKeyPath(), LOCAL_BACKEND_API_KEY: "my-api-key" },
);
expect(config.sessionApiKey).toBe("my-api-key");
});
});
describe("stack mode routing", () => {
const keyDirs: string[] = [];
afterEach(() => {
while (keyDirs.length > 0) {
const dir = keyDirs.pop();
if (dir) rmSync(dir, { recursive: true, force: true });
}
resetPersistedSessionApiKeyCache();
});
function envWithIsolatedKeyPath(
extra: Record<string, string> = {},
): Record<string, string> {
const dir = mkdtempSync(path.join(tmpdir(), "stack-mode-key-"));
keyDirs.push(dir);
return {
OH_SESSION_API_KEY_PATH: path.join(dir, "session-api-key.txt"),
PORT: "19802",
OH_CANVAS_SAFE_BACKEND_PORT: "19800",
OH_CANVAS_SAFE_AUTOMATION_PORT: "19801",
OH_CANVAS_SAFE_VITE_PORT: "19803",
...extra,
};
}
it("uses only a frontend default route in frontend-only mode", async () => {
const config = await buildConfig(
{ frontendOnly: true },
envWithIsolatedKeyPath(),
);
expect(config.launchFrontend).toBe(true);
expect(config.launchAgentServer).toBe(false);
expect(config.launchAutomation).toBe(false);
expect(getLocalServiceRoutes(config)).toEqual([]);
expect(getFrontendBackend(config)).toBe(
`http://localhost:${config.vitePort}`,
);
expect(buildRouteArgs(getLocalServiceRoutes(config))).toEqual([]);
});
it("does not bake a host workspace path in frontend-only mode by default", async () => {
const config = await buildConfig(
{ frontendOnly: true },
envWithIsolatedKeyPath(),
);
expect(config.viteWorkingDir).toBeUndefined();
});
it("honors explicit frontend-only VITE_WORKING_DIR values", async () => {
const config = await buildConfig(
{ frontendOnly: true },
envWithIsolatedKeyPath({ VITE_WORKING_DIR: "workspace/project" }),
);
expect(config.viteWorkingDir).toBe("workspace/project");
});
it("bakes the host workspace path when this launcher starts the agent-server", async () => {
const config = await buildConfig({}, envWithIsolatedKeyPath());
expect(config.viteWorkingDir).toBe(
path.join(config.stateDir, "workspaces"),
);
});
it("points frontend-only Vite at a separately running backend by default", async () => {
const config = await buildConfig(
{ frontendOnly: true },
envWithIsolatedKeyPath(),
);
expect(buildViteBackendEnv(config, {})).toEqual({
VITE_BACKEND_HOST: "127.0.0.1:8000",
});
});
it("keeps full-stack Vite pointed at this launcher's ingress", async () => {
const config = await buildConfig({}, envWithIsolatedKeyPath());
expect(buildViteBackendEnv(config, {})).toEqual({
VITE_BACKEND_HOST: `127.0.0.1:${config.ingressPort}`,
});
});
it("binds Vite to loopback and injects the key by default", async () => {
const config = await buildConfig({}, envWithIsolatedKeyPath());
expect(buildViteFrontendEnv(config)).toMatchObject({
VITE_BIND_HOST: "127.0.0.1",
VITE_SESSION_API_KEY: config.sessionApiKey,
});
expect(buildViteFrontendEnv(config)).not.toHaveProperty(
"VITE_AUTH_REQUIRED",
);
});
it("keeps the session key out of an off-loopback Vite origin", async () => {
const config = await buildConfig(
{ host: "0.0.0.0" },
envWithIsolatedKeyPath(),
);
const viteEnv = buildViteFrontendEnv(config);
expect(viteEnv.VITE_BIND_HOST).toBe("0.0.0.0");
expect(viteEnv).not.toHaveProperty("VITE_SESSION_API_KEY");
expect(viteEnv.VITE_AUTH_REQUIRED).toBe("true");
});
it("makes the key-free ingress reachable to Docker conversations", async () => {
const config = await buildConfig(
{},
envWithIsolatedKeyPath({ OH_CONVERSATION_RUNTIME: "docker" }),
);
expect(config.bindHost).toBe("0.0.0.0");
expect(buildViteFrontendEnv(config)).not.toHaveProperty(
"VITE_SESSION_API_KEY",
);
});
it("honors an explicit loopback override in Docker conversation mode", async () => {
const config = await buildConfig(
{},
envWithIsolatedKeyPath({
OH_CONVERSATION_RUNTIME: "docker",
OH_BIND_HOST: "127.0.0.1",
}),
);
expect(config.bindHost).toBe("127.0.0.1");
});
it("keeps the session key out of public-mode Vite on loopback", async () => {
const config = await buildConfig(
{ public: true },
envWithIsolatedKeyPath({ LOCAL_BACKEND_API_KEY: "public-key" }),
);
const viteEnv = buildViteFrontendEnv(config);
expect(viteEnv.VITE_BIND_HOST).toBe("127.0.0.1");
expect(viteEnv).not.toHaveProperty("VITE_SESSION_API_KEY");
expect(viteEnv.VITE_AUTH_REQUIRED).toBe("true");
});
it("allows frontend-only Vite to target an explicit backend URL", async () => {
const config = await buildConfig(
{ frontendOnly: true },
envWithIsolatedKeyPath(),
);
expect(
buildViteBackendEnv(config, {
VITE_BACKEND_BASE_URL: "https://backend.example.test",
}),
).toEqual({
VITE_BACKEND_HOST: "backend.example.test",
VITE_USE_TLS: "true",
});
});
it("respects an explicit VITE_USE_TLS override with VITE_BACKEND_BASE_URL", async () => {
const config = await buildConfig(
{ frontendOnly: true },
envWithIsolatedKeyPath(),
);
expect(
buildViteBackendEnv(config, {
VITE_BACKEND_BASE_URL: "https://backend.example.test",
VITE_USE_TLS: "false",
}),
).toEqual({
VITE_BACKEND_HOST: "backend.example.test",
});
});
it("does not set VITE_USE_TLS for http:// VITE_BACKEND_BASE_URL", async () => {
const config = await buildConfig(
{ frontendOnly: true },
envWithIsolatedKeyPath(),
);
expect(
buildViteBackendEnv(config, {
VITE_BACKEND_BASE_URL: "http://backend.example.test",
}),
).toEqual({
VITE_BACKEND_HOST: "backend.example.test",
});
});
it("routes only local services through IPv4 in backend-only mode", async () => {
const config = await buildConfig(
{ backendOnly: true },
envWithIsolatedKeyPath(),
);
expect(config.launchFrontend).toBe(false);
expect(config.launchAgentServer).toBe(true);
expect(config.launchAutomation).toBe(true);
expect(getFrontendBackend(config)).toBeNull();
const routes = getLocalServiceRoutes(config);
expect(routes).toContainEqual([
"/api/automation",
`http://127.0.0.1:${config.autoBackendPort}`,
]);
expect(routes).toContainEqual([
"/api",
`http://127.0.0.1:${config.agentServerPort}`,
]);
const routeArgs = buildRouteArgs(routes);
expect(routeArgs).toContain(
`/api/automation=http://127.0.0.1:${config.autoBackendPort}`,
);
expect(routeArgs).toContain(
`/server_info=http://127.0.0.1:${config.agentServerPort}`,
);
expect(routeArgs).not.toContain("--default");
});
it("routes the editor base path to the vscode port in the stock config", async () => {
// The whole point of the base path is that a stock launcher β no
// INGRESS_ROUTES, no OH_VSCODE_BASE_PATH β already reaches the editor
// through the single ingress origin. Both the outer ingress and the
// static-server route list are built from getLocalServiceRoutes, so
// asserting it here covers both.
const config = await buildConfig({}, envWithIsolatedKeyPath());
expect(config.vscodeBasePath).toBe("/vscode");
const routes = getLocalServiceRoutes(config);
expect(routes).toContainEqual([
config.vscodeBasePath,
`http://127.0.0.1:${config.vscodePort}`,
]);
expect(buildRouteArgs(routes)).toContain(
`/vscode=http://127.0.0.1:${config.vscodePort}`,
);
// The editor must not collide with the agent-server or automation ports;
// it is a separate process reached through the same origin.
expect(config.vscodePort).not.toBe(config.agentServerPort);
expect(config.vscodePort).not.toBe(config.autoBackendPort);
});
it("passes the agent-server a base path matching the ingress route", async () => {
// The advertised URL and the route that serves it come from two different
// places (agent-server's /api/vscode/url vs. the proxy route table). They
// only agree because both read the same config value β assert that rather
// than each side in isolation.
const config = await buildConfig({}, envWithIsolatedKeyPath());
const env = buildAgentServerEnv(
buildSafeDevConfig(process.cwd(), {
...envWithIsolatedKeyPath(),
OH_CANVAS_SAFE_BACKEND_PORT: String(config.agentServerPort),
OH_CANVAS_SAFE_VSCODE_PORT: String(config.vscodePort),
}),
{ vscodeBasePath: config.vscodeBasePath },
);
expect(env.OH_VSCODE_BASE_PATH).toBe(config.vscodeBasePath);
expect(env.OH_VSCODE_PORT).toBe(String(config.vscodePort));
const [, vscodeBackend] =
getLocalServiceRoutes(config).find(
([prefix]) => prefix === env.OH_VSCODE_BASE_PATH,
) ?? [];
expect(vscodeBackend).toBe(`http://127.0.0.1:${env.OH_VSCODE_PORT}`);
});
it("preserves the editor prefix rather than stripping it", async () => {
// openvscode-server is launched with --server-base-path, so it generates
// its HTTP and WebSocket URLs beneath the prefix and only answers there.
// A router that stripped the prefix would 404 every asset.
const config = await buildConfig({}, envWithIsolatedKeyPath());
const routes = Object.fromEntries(getLocalServiceRoutes(config));
const route = createRouter(routes);
const vscodeBackend = `http://127.0.0.1:${config.vscodePort}`;
expect(route("/vscode")).toBe(vscodeBackend);
expect(route("/vscode/")).toBe(vscodeBackend);
// Workbench assets and the WebSocket upgrade path both sit under the
// prefix; the proxy forwards req.url unchanged, so matching is all that
// is needed for the prefix to survive.
expect(route("/vscode/static/out/vs/workbench/workbench.web.main.js")).toBe(
vscodeBackend,
);
expect(route("/vscode/stable-abc/?tkn=k")).toBe(vscodeBackend);
// Longest-prefix matching must not let /vscode swallow /api or vice versa.
expect(route("/api/vscode/url")).toBe(
`http://127.0.0.1:${config.agentServerPort}`,
);
});
it("addresses the agent-server over IPv4 for readiness and secret seeding", async () => {
const config = await buildConfig({}, envWithIsolatedKeyPath());
// The launcher starts the agent-server with `--host 127.0.0.1`, so the
// readiness probe (`/server_info`), the secret-seeding request, and the
// automation backend's AUTOMATION_AGENT_SERVER_URL must all skip the
// `localhost` lookup that resolves to ::1 first on Windows.
expect(getAgentServerBaseUrl(config)).toBe(
`http://127.0.0.1:${config.agentServerPort}`,
);
});
it("rejects the editor prefix when no agent-server is launched", async () => {
// Without an agent-server there is no editor behind the prefix. Falling
// back to index.html would answer an editor request with the canvas shell.
const config = await buildConfig(
{ frontendOnly: true },
envWithIsolatedKeyPath(),
);
expect(getLocalServiceRoutes(config)).toEqual([]);
expect(getRejectPrefixes(config)).toContain("/vscode");
});
it("rejects mutually exclusive partial-stack modes", async () => {
await expect(
buildConfig(
{ frontendOnly: true, backendOnly: true },
envWithIsolatedKeyPath(),
),
).rejects.toThrow(/cannot be used together/);
});
});
describe("setServiceLogListener", () => {
afterEach(() => {
// Always clear the listener so it doesn't leak between tests.
setServiceLogListener(null);
});
it("forwards stdout, stderr, and exit lines to the listener", async () => {
const captured: Array<{ name: string; line: string; level: string }> = [];
setServiceLogListener((name: string, line: string, level: string) => {
captured.push({ name, line, level });
});
// Spawn a tiny inline script that writes to stdout, stderr, and exits
// non-zero so we exercise all three log paths. `process.execPath` is
// the same Node binary running the test so this is portable.
const proc = spawnService(
"log-listener-test",
process.execPath,
[
"-e",
// Use double-quoted JS to avoid shell quoting differences.
'process.stdout.write("hello-stdout\\n"); process.stderr.write("hello-stderr\\n"); process.exit(2);',
],
{},
);
await once(proc, "exit");
// Give the stdout/stderr 'data' handlers and the exit handler a tick to
// run after the process has actually exited.
await delay(50);
const lines = captured.map((c) => `${c.level}:${c.line}`);
expect(lines).toContain("stdout:hello-stdout");
expect(lines).toContain("stderr:hello-stderr");
expect(lines).toContain("error:exited with code 2");
// Every captured line must be tagged with our service name.
expect(captured.every((c) => c.name === "log-listener-test")).toBe(true);
});
it("is a no-op once the listener is cleared", async () => {
const captured: string[] = [];
setServiceLogListener((_n: string, line: string) => captured.push(line));
setServiceLogListener(null);
const proc = spawnService(
"log-listener-clear-test",
process.execPath,
["-e", 'process.stdout.write("should-not-be-seen\\n");'],
{},
);
await once(proc, "exit");
await delay(50);
expect(captured).toHaveLength(0);
});
it("ignores non-function values without throwing", () => {
// Passing anything that isn't a function (undefined, null, a string) must
// be safe β main() relies on this so it can always call
// setServiceLogListener(onServiceLog) regardless of whether the embedder
// supplied a callback.
expect(() => setServiceLogListener(undefined)).not.toThrow();
expect(() => setServiceLogListener(null)).not.toThrow();
expect(() => setServiceLogListener("not a function")).not.toThrow();
});
it("swallows errors thrown by the listener so a buggy embedder cannot kill the dev stack", async () => {
// A listener that throws on every call must not propagate; the stdout
// handler in spawnService is fire-and-forget. We can't easily observe
// an unhandled rejection from within Vitest, but if we can run a process
// to completion without the test failing, the catch is doing its job.
setServiceLogListener(() => {
throw new Error("buggy listener");
});
const proc = spawnService(
"log-listener-throws-test",
process.execPath,
["-e", 'process.stdout.write("line\\n"); process.exit(0);'],
{},
);
const [code] = await once(proc, "exit");
expect(code).toBe(0);
});
});
describe("dev-with-automation CLI", () => {
it.skipIf(process.platform === "win32")(
"cleans up detached services when the launcher receives SIGHUP",
async () => {
const moduleUrl = pathToFileURL(
path.join(repoRoot, "scripts", "dev-with-automation.mjs"),
).href;
const fixtureSource = [
'import net from "node:net";',
"const server = net.createServer(() => {});",
'server.listen(0, "127.0.0.1", () => console.log("READY", process.pid, server.address().port));',
].join("\n");
const supervisorSource = [
`import { spawnService } from ${JSON.stringify(moduleUrl)};`,
`const fixture = spawnService("fixture", process.execPath, ["--input-type=module", "--eval", ${JSON.stringify(fixtureSource)}]);`,
'console.log("SPAWNED", fixture.pid);',
"setInterval(() => {}, 1_000);",
].join("\n");
const supervisor = spawn(
process.execPath,
["--input-type=module", "--eval", supervisorSource],
{
cwd: repoRoot,
stdio: ["ignore", "pipe", "pipe"],
},
);
let output = "";
let fixturePid: number | undefined;
let fixturePort: number | undefined;
const capture = (chunk: Buffer) => {
output += chunk.toString();
const spawnedMatch = output.match(/SPAWNED (\d+)/);
const readyMatch = output.match(/READY \d+ (\d+)/);
if (spawnedMatch) fixturePid = Number(spawnedMatch[1]);
if (readyMatch) fixturePort = Number(readyMatch[1]);
};
supervisor.stdout.on("data", capture);
supervisor.stderr.on("data", capture);
try {
const readyDeadline = Date.now() + 5_000;
while (!fixturePort && Date.now() < readyDeadline) {
if (supervisor.exitCode !== null) break;
await delay(25);
}
expect(fixturePid, output).toBeDefined();
expect(fixturePort, output).toBeDefined();
supervisor.kill("SIGHUP");
const exitResult = await Promise.race([
once(supervisor, "exit").then(([code, signal]) => ({
code,
signal,
timedOut: false,
})),
delay(6_000).then(() => ({
code: null,
signal: null,
timedOut: true,
})),
]);
expect(exitResult.timedOut).toBe(false);
expect(exitResult).toMatchObject({ code: 0, signal: null });
const releaseDeadline = Date.now() + 2_000;
let portIsOpen = true;
while (portIsOpen && Date.now() < releaseDeadline) {
portIsOpen = await new Promise<boolean>((resolve) => {
const socket = net.connect(fixturePort!, "127.0.0.1");
socket.setTimeout(250);
socket.once("connect", () => {
socket.destroy();
resolve(true);
});
socket.once("error", () => resolve(false));
socket.once("timeout", () => {
socket.destroy();
resolve(false);
});
});
if (portIsOpen) await delay(50);
}
expect(portIsOpen).toBe(false);
} finally {
if (supervisor.exitCode === null) supervisor.kill("SIGKILL");
if (fixturePid) {
try {
process.kill(-fixturePid, "SIGKILL");
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
}
}
}
},
15_000,
);
// Runs the real `main()` with `--backend-only` and lets the caller decide
// what the automation backend does. `main()` starts it as
// `uv run --project <checkout> uvicorn ... --host 127.0.0.1 --port <port>`;
// the fake `uv` hands those arguments to `automationSource` (a Node ESM
// script). The agent-server is an in-process stub that answers every request,
// so the launcher reaches the automation wait without delay.
async function launchBackendOnly(automationSource: string) {
const moduleUrl = pathToFileURL(
path.join(repoRoot, "scripts", "dev-with-automation.mjs"),
).href;
const dir = mkdtempSync(path.join(tmpdir(), "automation-startup-"));
const bin = path.join(dir, "bin");
const checkout = path.join(dir, "automation");
mkdirSync(bin);
mkdirSync(checkout);
writeFileSync(path.join(checkout, "pyproject.toml"), "");
const automationScript = path.join(dir, "automation.mjs");
writeFileSync(automationScript, automationSource);
// `uvx` only has to exist; the agent-server is stubbed below.
writeFileSync(path.join(bin, "uvx"), "#!/bin/sh\nexit 0\n", {
mode: 0o755,
});
writeFileSync(
path.join(bin, "uv"),
`#!/bin/sh\nexec ${JSON.stringify(process.execPath)} ${JSON.stringify(automationScript)} "$@"\n`,
{ mode: 0o755 },
);
const ports: number[] = [];
for (let i = 0; i < 3; i += 1) {
const server = net.createServer();
await new Promise<void>((resolve) =>
server.listen(0, "127.0.0.1", resolve),
);
ports.push((server.address() as net.AddressInfo).port);
await new Promise((resolve) => server.close(resolve));
}
const [ingressPort, agentServerPort, automationPort] = ports;
const launcherScript = path.join(dir, "launch.mjs");
writeFileSync(
launcherScript,
[
'import http from "node:http";',
`import { main } from ${JSON.stringify(moduleUrl)};`,
"const startAgentServer = (config) =>",
' http.createServer((_req, res) => res.end("{}")).listen(config.agentServerPort, "127.0.0.1");',
"main({ startAgentServer, agentServerReadyTimeoutMs: 10_000 })",
' .then(() => console.log("LAUNCHED"))',
' .catch((error) => { console.log("FAILED:", error.message); process.exit(1); });',
].join("\n"),
);
const launcher = spawn(
process.execPath,
[launcherScript, "--backend-only", "--port", String(ingressPort)],
{
cwd: repoRoot,
env: {
...process.env,
PATH: `${bin}${path.delimiter}${process.env.PATH ?? ""}`,
HOME: dir,
OH_CANVAS_SAFE_STATE_DIR: path.join(dir, "state"),
OH_CANVAS_SAFE_BACKEND_PORT: String(agentServerPort),
OH_CANVAS_SAFE_AUTOMATION_PORT: String(automationPort),
OH_AUTOMATION_LOCAL_PATH: checkout,
},
stdio: ["ignore", "pipe", "pipe"],
},
);
let output = "";
launcher.stdout.on("data", (chunk) => {
output += chunk.toString();
});
launcher.stderr.on("data", (chunk) => {
output += chunk.toString();
});
const exited = once(launcher, "exit").then(([code]) => code as number);
return {
ingressPort,
automationPort,
output: () => output,
exitCode: (timeoutMs: number) =>
Promise.race([exited, delay(timeoutMs).then(() => "timed out")]),
async waitForOutput(text: string, timeoutMs: number) {
const deadline = Date.now() + timeoutMs;
while (!output.includes(text) && Date.now() < deadline) {
if (launcher.exitCode !== null) break;
await delay(50);
}
return output.includes(text);
},
async stop() {
// SIGTERM lets the launcher's shutdown handler stop its detached
// services; that is also the cleanup when a regression leaves it up.
if (launcher.exitCode === null) {
launcher.kill("SIGTERM");
await Promise.race([exited, delay(6_000)]);
if (launcher.exitCode === null) launcher.kill("SIGKILL");
}
rmSync(dir, { recursive: true, force: true });
},
};
}
const isListening = (port: number) =>
new Promise<boolean>((resolve) => {
const socket = net.connect(port, "127.0.0.1");
socket.once("connect", () => {
socket.destroy();
resolve(true);
});
socket.once("error", () => resolve(false));
});
it.skipIf(process.platform === "win32")(
"stops the stack and exits 1 when the automation backend exits during startup",
async () => {
// Exits the way automation does when a database migration fails.
const stack = await launchBackendOnly(
'console.error("Failed to apply SQLite migrations");\nprocess.exit(3);\n',
);
try {
const exitCode = await stack.exitCode(25_000);
const output = stack.output();
expect(exitCode, output).toBe(1);
// The stack is announced without waiting for automation, then
// stopped once automation exits. "Ingress:" is the banner's first
// entry, printed in every launch mode.
const banner = output.indexOf("Ingress:");
const failure = output.indexOf(
"The automation backend exited during startup (code 3).",
);
expect(banner, output).toBeGreaterThan(-1);
expect(failure, output).toBeGreaterThan(banner);
expect(await isListening(stack.ingressPort)).toBe(false);
} finally {
await stack.stop();
}
},
30_000,
);
it.skipIf(process.platform === "win32")(
"announces the stack without waiting for the automation backend",
async () => {
// Listening but not ready yet: the first two health probes get 503, so
// "Ready" is only logged after the launcher has polled and waited.
const stack = await launchBackendOnly(
[
'import http from "node:http";',
'const port = Number(process.argv[process.argv.indexOf("--port") + 1]);',
"let probes = 0;",
"http",
" .createServer((req, res) => {",
' const healthy = req.url === "/api/automation/health" && ++probes > 2;',
" res.writeHead(healthy ? 200 : 503).end(healthy ? '{\"status\":\"ok\"}' : '');",
" })",
' .listen(port, "127.0.0.1");',
"// Never outlive the test, even if the launcher is killed.",
"setTimeout(() => process.exit(0), 30_000);",
].join("\n"),
);
try {
expect(
await stack.waitForOutput("LAUNCHED", 20_000),
stack.output(),
).toBe(true);
const readyLine = `Ready at http://127.0.0.1:${stack.automationPort}/api/automation/health`;
expect(
await stack.waitForOutput(readyLine, 20_000),
stack.output(),
).toBe(true);
const output = stack.output();
const ready = output.indexOf(readyLine);
expect(output.indexOf("Ingress:"), output).toBeGreaterThan(-1);
expect(output.indexOf("Ingress:"), output).toBeLessThan(ready);
// A healthy start keeps the stack up.
expect(await stack.exitCode(1_000)).toBe("timed out");
expect(await isListening(stack.ingressPort)).toBe(true);
} finally {
await stack.stop();
}
},
30_000,
);
it("shows help with --help flag", async () => {
const child = spawn(
process.execPath,
["scripts/dev-with-automation.mjs", "--help"],
{
cwd: repoRoot,
stdio: ["ignore", "pipe", "pipe"],
},
);
let output = "";
child.stdout.on("data", (chunk) => {
output += chunk.toString();
});
const [code] = await once(child, "exit");
expect(code).toBe(0);
expect(output).toContain("Agent Canvas + Automation Development Stack");
expect(output).toContain("--port");
expect(output).toContain("--automation-ref");
expect(output).toContain("--automation-repo");
expect(output).toContain("--static");
expect(output).toContain("--dynamic");
expect(output).toContain("--frontend-only");
expect(output).toContain("--backend-only");
expect(output).toContain("OH_AUTOMATION_GIT_REF");
expect(output).toContain("OH_AGENT_SERVER_LOCAL_PATH");
expect(output).toContain("OPENHANDS_AUTOMATION_API_KEY");
expect(output).toContain("SECRETS:");
});
it("fails fast with a clear error when OH_AGENT_SERVER_LOCAL_PATH is invalid", async () => {
// Arrange: an absolute but empty directory β `validateLocalAgentServerPath`
// requires the four workspace subdirs (openhands-agent-server, openhands-sdk,
// openhands-tools, openhands-workspace) and must reject this.
const emptyDir = mkdtempSync(path.join(tmpdir(), "bad-sdk-"));
// Stub a no-op `uvx` on PATH so `checkPrerequisites` passes even on CI
// runners that don't have uv installed. The prerequisite check must
// succeed so the LOCAL_PATH validation guard (the actual subject of this
// test, which runs immediately after) is exercised.
const isWindows = process.platform === "win32";
const stubBinDir = mkdtempSync(path.join(tmpdir(), "stub-bin-"));
if (isWindows) {
writeFileSync(path.join(stubBinDir, "uvx.cmd"), "@exit /b 0\r\n");
} else {
writeFileSync(path.join(stubBinDir, "uvx"), "#!/bin/sh\nexit 0\n", {
mode: 0o755,
});
}
// Act: spawn `dev-with-automation.mjs` with that path set. Stubbed `uvx`
// is prepended to PATH so the prerequisite check passes; the validation
// guard must trip *after* those checks but *before* port allocation, so
// we can assert on both the error message and the absence of side effects.
const child = spawn(process.execPath, ["scripts/dev-with-automation.mjs"], {
cwd: repoRoot,
env: {
PATH: `${stubBinDir}${path.delimiter}${process.env.PATH ?? ""}`,
HOME: process.env.HOME ?? "",
OH_AGENT_SERVER_LOCAL_PATH: emptyDir,
// Windows needs these for `where.exe` to resolve the stub and npm
...(isWindows
? {
PATHEXT: process.env.PATHEXT ?? ".CMD;.EXE;.BAT;.COM",
SystemRoot: process.env.SystemRoot ?? "",
USERPROFILE: process.env.USERPROFILE ?? "",
}
: {}),
},
stdio: ["ignore", "pipe", "pipe"],
});
let output = "";
child.stdout.on("data", (chunk) => {
output += chunk.toString();
});
child.stderr.on("data", (chunk) => {
output += chunk.toString();
});
const exitResult = await Promise.race([
once(child, "exit").then(([code, signal]) => ({
code,
signal,
timedOut: false,
})),
delay(10_000).then(() => ({ code: null, signal: null, timedOut: true })),
]);
if (exitResult.timedOut) {
child.kill("SIGKILL");
}
try {
// Assert: process exits non-zero, surfaces the validator's error, and
// never reaches `buildConfig` (no `[ports] Allocating ports...` log).
expect(exitResult.timedOut).toBe(false);
expect(exitResult.code).toBe(1);
expect(output).toContain(
"OH_AGENT_SERVER_LOCAL_PATH is missing expected workspace package",
);
expect(output).not.toContain("Allocating ports");
} finally {
rmSync(emptyDir, { recursive: true, force: true });
rmSync(stubBinDir, { recursive: true, force: true });
}
});
it("exits promptly when uvx is missing", async () => {
const child = spawn(process.execPath, ["scripts/dev-with-automation.mjs"], {
cwd: repoRoot,
env: {
PATH: "",
},
stdio: ["ignore", "pipe", "pipe"],
});
let output = "";
child.stdout.on("data", (chunk) => {
output += chunk.toString();
});
child.stderr.on("data", (chunk) => {
output += chunk.toString();
});
const exitResult = await Promise.race([
once(child, "exit").then(([code, signal]) => ({
code,
signal,
timedOut: false,
})),
delay(4_000).then(() => ({ code: null, signal: null, timedOut: true })),
]);
if (exitResult.timedOut) {
child.kill("SIGKILL");
}
expect(exitResult.timedOut).toBe(false);
expect(exitResult.code).toBe(1);
expect(output).toContain("uvx");
});
});
describe("backend logging defaults", () => {
// Minimal SafeDevConfig for buildAgentServerEnv; only the fields it reads
// matter, but it accesses them directly rather than via optional chaining.
const baseConfig = () => ({
cwd: process.cwd(),
backendPort: 18000,
vscodePort: 18001,
vscodeBasePath: "/vscode",
stateDir: "/tmp/state",
tmuxTmpDir: "/tmp/tmux",
conversationsPath: "/tmp/conversations",
workspacesPath: "/tmp/workspaces",
bashEventsDir: "/tmp/bash-events",
backendBaseUrl: "http://127.0.0.1:18000",
backendHost: "127.0.0.1",
workingDir: process.cwd(),
secretKey: "secret",
sessionApiKey: "session",
canvasToolsDir: "/tmp/tools",
extensionsDir: null,
});
it("quiets the automation service by default", () => {
const env = buildBackendLogEnv({ automation: true, env: {} });
expect(env.LOG_LEVEL).toBe("WARNING");
expect(env.AUTOMATION_LOG_LEVEL).toBe("WARNING");
});
it("leaves AUTOMATION_LOG_LEVEL unset for the agent-server", () => {
// The agent-server does not read AUTOMATION_LOG_LEVEL; setting it there
// would suggest it has an effect it does not.
const env = buildBackendLogEnv({ env: {} });
expect(env.LOG_LEVEL).toBe("WARNING");
expect(env).not.toHaveProperty("AUTOMATION_LOG_LEVEL");
});
it("honors an explicit LOG_LEVEL from the caller's environment", () => {
const env = buildBackendLogEnv({
automation: true,
env: { LOG_LEVEL: "INFO" },
});
expect(env.LOG_LEVEL).toBe("INFO");
expect(env.AUTOMATION_LOG_LEVEL).toBe("INFO");
});
it("lets AUTOMATION_LOG_LEVEL diverge from LOG_LEVEL", () => {
const env = buildBackendLogEnv({
automation: true,
env: { LOG_LEVEL: "ERROR", AUTOMATION_LOG_LEVEL: "DEBUG" },
});
expect(env.LOG_LEVEL).toBe("ERROR");
expect(env.AUTOMATION_LOG_LEVEL).toBe("DEBUG");
});
it("raises both services to DEBUG under --verbose, overriding the environment", () => {
const env = buildBackendLogEnv({
verbose: true,
automation: true,
env: { LOG_LEVEL: "ERROR" },
});
expect(env.LOG_LEVEL).toBe("DEBUG");
expect(env.AUTOMATION_LOG_LEVEL).toBe("DEBUG");
});
it("passes the same level to uvicorn as to the automation service", () => {
const args = buildAutomationLogArgs({ autoBackendPort: 18001 }, {});
expect(args).toEqual([
"--host",
"127.0.0.1",
"--port",
"18001",
"--log-level",
"warning",
]);
});
it("passes debug to uvicorn under --verbose", () => {
const args = buildAutomationLogArgs(
{ autoBackendPort: 18001, verbose: true },
{},
);
expect(args.at(-1)).toBe("debug");
});
// Uvicorn validates --log-level with a click.Choice and exits 2 on anything
// outside its set, which takes the whole dev stack down. The app accepts
// more than Uvicorn does, so an explicit override must be narrowed rather
// than forwarded verbatim.
describe("narrows the Uvicorn --log-level to a value Uvicorn accepts", () => {
const UVICORN_ACCEPTS = [
"critical",
"error",
"warning",
"info",
"debug",
"trace",
];
it("keeps every level Uvicorn already accepts", () => {
for (const level of UVICORN_ACCEPTS) {
expect(uvicornLogLevel(level)).toBe(level);
expect(uvicornLogLevel(level.toUpperCase())).toBe(level);
}
});
it("maps the Python aliases Uvicorn rejects", () => {
expect(uvicornLogLevel("WARN")).toBe("warning");
expect(uvicornLogLevel("warn")).toBe("warning");
expect(uvicornLogLevel("FATAL")).toBe("critical");
expect(uvicornLogLevel("fatal")).toBe("critical");
});
it("maps numeric levels onto the nearest Uvicorn name", () => {
expect(uvicornLogLevel("50")).toBe("critical");
expect(uvicornLogLevel("40")).toBe("error");
expect(uvicornLogLevel("30")).toBe("warning");
expect(uvicornLogLevel("20")).toBe("info");
expect(uvicornLogLevel("10")).toBe("debug");
expect(uvicornLogLevel("5")).toBe("trace");
});
it("falls back to Uvicorn's own default for unrepresentable values", () => {
// `NOTSET` means "inherit", not "most verbose", and Uvicorn has no
// equivalent; the pre-PR launchers passed no --log-level at all, which
// left Uvicorn at `info`.
expect(uvicornLogLevel("NOTSET")).toBe("info");
expect(uvicornLogLevel("0")).toBe("info");
expect(uvicornLogLevel("")).toBe("info");
expect(uvicornLogLevel(undefined)).toBe("info");
expect(uvicornLogLevel("verbose")).toBe("info");
});
it("never returns a value outside Uvicorn's accepted set", () => {
const inputs = [
"WARN",
"FATAL",
"NOTSET",
"30",
"0",
"",
"bogus",
"999999999999999999999",
" 30 ",
"warning",
];
for (const input of inputs) {
expect(UVICORN_ACCEPTS).toContain(uvicornLogLevel(input));
}
});
it("narrows an explicit LOG_LEVEL alias in the built args", () => {
// The regression: `LOG_LEVEL=WARN npm run dev` aborted Uvicorn.
const args = buildAutomationLogArgs(
{ autoBackendPort: 18001 },
{ LOG_LEVEL: "WARN" },
);
expect(args.at(-1)).toBe("warning");
});
it("leaves the app's LOG_LEVEL env untouched for an alias", () => {
// The app reads LOG_LEVEL through Python's logging module, which does
// accept WARN β only the Uvicorn argument is narrowed.
const env = buildBackendLogEnv({
automation: true,
env: { LOG_LEVEL: "WARN" },
});
expect(env.LOG_LEVEL).toBe("WARN");
expect(env.AUTOMATION_LOG_LEVEL).toBe("WARN");
});
});
it("gives the agent-server the quiet default without an opt-out needed", () => {
const env = buildAgentServerEnv(baseConfig(), { env: {} });
expect(env.LOG_LEVEL).toBe("WARNING");
});
it("raises the agent-server to DEBUG under --verbose", () => {
const env = buildAgentServerEnv(baseConfig(), { env: {}, verbose: true });
expect(env.LOG_LEVEL).toBe("DEBUG");
});
});
describe("buildMarsWebEnv", () => {
it("puts the bridge on the ingress behind the session key, off the static child", () => {
const config = { sessionApiKey: "stack-key", marsWebBridge: true } as never;
expect(buildMarsWebEnv("ingress", config)).toEqual({
MARS_WEB_KEY: "stack-key",
});
expect(buildMarsWebEnv("static", config)).toEqual({ MARS_WEB: "0" });
});
it("mounts nothing without a session key", () => {
expect(
buildMarsWebEnv("ingress", { marsWebBridge: true } as never),
).toEqual({ MARS_WEB: "0" });
});
it("mounts nothing under Electron (marsWebBridge: false), even with a key", () => {
expect(
buildMarsWebEnv("ingress", {
sessionApiKey: "k",
marsWebBridge: false,
} as never),
).toEqual({ MARS_WEB: "0" });
});
});