feat: add Screeps console monitoring with configurable error handling and shard support (#84)

Reviewed-on: #84
2026-05-16 19:44:39 +02:00
parent be3c8ac7d2
commit bf52580bf3
12 changed files with 3124 additions and 18 deletions
@@ -0,0 +1,507 @@
+import { vi, describe, it, expect, beforeEach, afterEach } from "vitest";
+
+// ── mock @actions/core so tests never touch real CI outputs ─────────────────
+vi.mock("@actions/core", () => ({
+  info: vi.fn(),
+  error: vi.fn(),
+  warning: vi.fn(),
+  setFailed: vi.fn(),
+  setOutput: vi.fn(),
+  startGroup: vi.fn(),
+  endGroup: vi.fn(),
+}));
+
+// ── mock @actions/artifact so tests never attempt real uploads ──────────────
+vi.mock("@actions/artifact", () => ({
+  DefaultArtifactClient: vi.fn().mockImplementation(() => ({
+    uploadArtifact: vi.fn().mockResolvedValue({}),
+  })),
+}));
+
+import * as core from "@actions/core";
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+import {
+  isOfficialServer,
+  buildSubscribePath,
+  detectTraceback,
+  detectWarning,
+  buildProgressMessage,
+  writeLogFile,
+  handleConsoleEvent,
+  monitorConsole,
+} from "../monitor.js";
+
+// ────────────────────────────────────────────────────────────────────────────
+// Pure helpers
+// ────────────────────────────────────────────────────────────────────────────
+
+describe("isOfficialServer", () => {
+  it("returns true for screeps.com", () => {
+    expect(isOfficialServer("screeps.com")).toBe(true);
+  });
+
+  it("returns false for a private hostname", () => {
+    expect(isOfficialServer("builder64")).toBe(false);
+  });
+
+  it("returns false for an IP address", () => {
+    expect(isOfficialServer("192.168.1.10")).toBe(false);
+  });
+});
+
+describe("buildSubscribePath", () => {
+  it("returns shard0/console for official server (no shard provided)", () => {
+    expect(buildSubscribePath("screeps.com")).toBe("shard0/console");
+  });
+
+  it("returns console for private server (no shard provided)", () => {
+    expect(buildSubscribePath("builder64")).toBe("console");
+  });
+
+  it("returns <shard>/console when shard is provided (official)", () => {
+    expect(buildSubscribePath("screeps.com", "shard3")).toBe("shard3/console");
+  });
+
+  it("returns <shard>/console when shard is provided (private)", () => {
+    expect(buildSubscribePath("builder64", "myshard")).toBe("myshard/console");
+  });
+});
+
+describe("detectTraceback", () => {
+  it("returns true when error contains a stack frame line", () => {
+    const error =
+      "TypeError: Cannot read properties of undefined\n    at Object.<anonymous> (main:1:42)";
+    expect(detectTraceback(error)).toBe(true);
+  });
+
+  it("returns false for a plain error message without stack frames", () => {
+    expect(detectTraceback("Something went wrong")).toBe(false);
+  });
+
+  it("returns false for null", () => {
+    expect(detectTraceback(null)).toBe(false);
+  });
+
+  it("returns false for undefined", () => {
+    expect(detectTraceback(undefined)).toBe(false);
+  });
+
+  it("returns false for an empty string", () => {
+    expect(detectTraceback("")).toBe(false);
+  });
+});
+
+describe("detectWarning", () => {
+  it("returns true for a line with orange font tag", () => {
+    const lines = ["<font color='orange'>WARN: low energy</font>"];
+    expect(detectWarning(lines)).toBe(true);
+  });
+
+  it("returns true for a line with yellow font tag", () => {
+    const lines = ['<font color="yellow">WARN: something</font>'];
+    expect(detectWarning(lines)).toBe(true);
+  });
+
+  it("returns false for a plain log line", () => {
+    expect(detectWarning(["Tick 123: harvesting"])).toBe(false);
+  });
+
+  it("returns false for an empty array", () => {
+    expect(detectWarning([])).toBe(false);
+  });
+
+  it("returns false for null", () => {
+    expect(detectWarning(null)).toBe(false);
+  });
+
+  it("returns true when only one line in a mixed array is a warning", () => {
+    const lines = ["normal line", "<font color='orange'>warn</font>"];
+    expect(detectWarning(lines)).toBe(true);
+  });
+});
+
+describe("buildProgressMessage", () => {
+  it("formats correctly at 0 elapsed", () => {
+    expect(buildProgressMessage(0, 50)).toBe("[Monitor] 0/50 ticks elapsed...");
+  });
+
+  it("formats correctly midway", () => {
+    expect(buildProgressMessage(25, 50)).toBe(
+      "[Monitor] 25/50 ticks elapsed...",
+    );
+  });
+
+  it("formats correctly at 100%", () => {
+    expect(buildProgressMessage(50, 50)).toBe(
+      "[Monitor] 50/50 ticks elapsed...",
+    );
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// handleConsoleEvent
+// ────────────────────────────────────────────────────────────────────────────
+
+describe("handleConsoleEvent", () => {
+  let state;
+  let stdoutBuffer;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    state = { sawTraceback: false, sawErrorLog: false, sawWarningLog: false };
+    stdoutBuffer = [];
+  });
+
+  const makeEvent = (log = [], results = [], error = null) => ({
+    data: { messages: { log, results }, error },
+  });
+
+  it("calls core.info for each stdout line when logToFile=false", () => {
+    const event = makeEvent(["line1", "line2"]);
+    handleConsoleEvent(event, { logToFile: false }, stdoutBuffer, state);
+    expect(core.info).toHaveBeenCalledWith("line1");
+    expect(core.info).toHaveBeenCalledWith("line2");
+    expect(stdoutBuffer).toHaveLength(0);
+  });
+
+  it("buffers stdout when logToFile=true; does not call core.info", () => {
+    const event = makeEvent(["line1", "line2"]);
+    handleConsoleEvent(event, { logToFile: true }, stdoutBuffer, state);
+    expect(core.info).not.toHaveBeenCalled();
+    expect(stdoutBuffer).toEqual(["line1", "line2"]);
+  });
+
+  it("includes results lines in output", () => {
+    const event = makeEvent([], ["result1"]);
+    handleConsoleEvent(event, { logToFile: false }, stdoutBuffer, state);
+    expect(core.info).toHaveBeenCalledWith("result1");
+  });
+
+  it("calls core.error when error field is non-empty", () => {
+    const event = makeEvent([], [], "Script crashed");
+    handleConsoleEvent(event, { logToFile: false }, stdoutBuffer, state);
+    expect(core.error).toHaveBeenCalledWith("Script crashed");
+    expect(state.sawErrorLog).toBe(true);
+  });
+
+  it("sets state.sawTraceback when error contains stack frames", () => {
+    const error = "TypeError: boom\n    at Object.<anonymous> (main:1:1)";
+    const event = makeEvent([], [], error);
+    handleConsoleEvent(event, { logToFile: false }, stdoutBuffer, state);
+    expect(state.sawTraceback).toBe(true);
+    expect(state.sawErrorLog).toBe(true);
+  });
+
+  it("does not set sawTraceback for plain error without stack frames", () => {
+    const event = makeEvent([], [], "Script error: low CPU");
+    handleConsoleEvent(event, { logToFile: false }, stdoutBuffer, state);
+    expect(state.sawTraceback).toBe(false);
+    expect(state.sawErrorLog).toBe(true);
+  });
+
+  it("sets state.sawWarningLog and calls core.warning for warn lines", () => {
+    const event = makeEvent(["<font color='orange'>low energy</font>"]);
+    handleConsoleEvent(event, { logToFile: false }, stdoutBuffer, state);
+    expect(state.sawWarningLog).toBe(true);
+    expect(core.warning).toHaveBeenCalled();
+  });
+
+  it("calls core.warning regardless of logToFile setting", () => {
+    const event = makeEvent(["<font color='orange'>warn line</font>"]);
+    handleConsoleEvent(event, { logToFile: true }, stdoutBuffer, state);
+    expect(core.warning).toHaveBeenCalled();
+  });
+
+  it("handles missing messages gracefully (no crash on empty event)", () => {
+    const event = { data: {} };
+    expect(() =>
+      handleConsoleEvent(event, { logToFile: false }, stdoutBuffer, state),
+    ).not.toThrow();
+  });
+
+  it("handles completely empty event gracefully", () => {
+    const event = {};
+    expect(() =>
+      handleConsoleEvent(event, { logToFile: false }, stdoutBuffer, state),
+    ).not.toThrow();
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// writeLogFile
+// ────────────────────────────────────────────────────────────────────────────
+
+describe("writeLogFile", () => {
+  let tempDir;
+  let tempFile;
+
+  beforeEach(async () => {
+    tempDir = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "monitor-test-"),
+    );
+    tempFile = path.join(tempDir, "log.txt");
+  });
+
+  afterEach(async () => {
+    await fs.promises.rm(tempDir, { recursive: true, force: true });
+  });
+
+  it("writes all lines to file joined by newlines", async () => {
+    await writeLogFile(["line1", "line2", "line3"], tempFile);
+    const content = await fs.promises.readFile(tempFile, "utf8");
+    expect(content).toBe("line1\nline2\nline3");
+  });
+
+  it("writes an empty file when given an empty array", async () => {
+    await writeLogFile([], tempFile);
+    const content = await fs.promises.readFile(tempFile, "utf8");
+    expect(content).toBe("");
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// monitorConsole — integration with mocked API
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Builds a mock ScreepsAPI that:
+ *  - api.time(shard) returns ticks from a list on each call
+ *  - api.socket.connect()   → resolves immediately
+ *  - api.socket.subscribe() → resolves immediately (stores the callback)
+ *  - api.socket.disconnect()→ no-op
+ */
+function buildMockApi({
+  ticks = [100, 101, 102, 103, 104, 105],
+  hostname = "builder64",
+} = {}) {
+  let tickIndex = 0;
+  let consoleCallback = null;
+
+  const socket = {
+    connect: vi.fn().mockResolvedValue(undefined),
+    subscribe: vi.fn().mockImplementation((_path, cb) => {
+      consoleCallback = cb;
+      return Promise.resolve();
+    }),
+    disconnect: vi.fn(),
+  };
+
+  const api = {
+    opts: { hostname },
+    time: vi.fn().mockImplementation(() => {
+      const t = ticks[Math.min(tickIndex, ticks.length - 1)];
+      tickIndex++;
+      return Promise.resolve({ time: t });
+    }),
+    socket,
+    // Expose so tests can fire console events
+    _fireConsole: (eventData) => {
+      if (consoleCallback) {
+        consoleCallback({ data: eventData });
+      }
+    },
+  };
+
+  return api;
+}
+
+const BASE_OPTS = {
+  monitor: 3,
+  logToFile: false,
+  onTraceback: "fail",
+  onErrorLog: "warn",
+  onWarningLog: "ignore",
+  monitorInterval: 2,
+  hostname: "builder64",
+};
+
+describe("monitorConsole", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns all three flags false on a clean run", async () => {
+    const api = buildMockApi({ ticks: [100, 101, 102, 103] });
+    const result = await monitorConsole(api, BASE_OPTS);
+    expect(result).toEqual({
+      sawTraceback: false,
+      sawErrorLog: false,
+      sawWarningLog: false,
+    });
+  });
+
+  it("calls api.socket.connect() exactly once", async () => {
+    const api = buildMockApi({ ticks: [100, 101, 102, 103] });
+    await monitorConsole(api, BASE_OPTS);
+    expect(api.socket.connect).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls api.socket.disconnect() after completion", async () => {
+    const api = buildMockApi({ ticks: [100, 101, 102, 103] });
+    await monitorConsole(api, BASE_OPTS);
+    expect(api.socket.disconnect).toHaveBeenCalledTimes(1);
+  });
+
+  it("subscribes to 'console' for a private server", async () => {
+    const api = buildMockApi({
+      hostname: "builder64",
+      ticks: [100, 101, 102, 103],
+    });
+    await monitorConsole(api, { ...BASE_OPTS, hostname: "builder64" });
+    expect(api.socket.subscribe).toHaveBeenCalledWith(
+      "console",
+      expect.any(Function),
+    );
+  });
+
+  it("subscribes to 'shard0/console' for the official server (default)", async () => {
+    const api = buildMockApi({
+      hostname: "screeps.com",
+      ticks: [100, 101, 102, 103],
+    });
+    await monitorConsole(api, { ...BASE_OPTS, hostname: "screeps.com" });
+    expect(api.socket.subscribe).toHaveBeenCalledWith(
+      "shard0/console",
+      expect.any(Function),
+    );
+  });
+
+  it("subscribes to custom shard when provided", async () => {
+    const api = buildMockApi({
+      hostname: "screeps.com",
+      ticks: [100, 101, 102, 103],
+    });
+    await monitorConsole(api, {
+      ...BASE_OPTS,
+      hostname: "screeps.com",
+      shard: "shard3",
+    });
+    expect(api.socket.subscribe).toHaveBeenCalledWith(
+      "shard3/console",
+      expect.any(Function),
+    );
+    // Verify polling also uses shard3
+    expect(api.time).toHaveBeenCalledWith("shard3");
+  });
+
+  it("returns sawTraceback=true when a traceback event arrives", async () => {
+    const api = buildMockApi({ ticks: [100, 101, 102, 103] });
+    // Schedule console event before poll advances
+    setTimeout(() => {
+      api._fireConsole({
+        messages: { log: [], results: [] },
+        error: "TypeError: boom\n    at Object.<anonymous> (main:1:1)",
+      });
+    }, 0);
+    const result = await monitorConsole(api, BASE_OPTS);
+    expect(result.sawTraceback).toBe(true);
+  });
+
+  it("returns sawErrorLog=true when an error (no traceback) event arrives", async () => {
+    const api = buildMockApi({ ticks: [100, 101, 102, 103] });
+    setTimeout(() => {
+      api._fireConsole({
+        messages: { log: [], results: [] },
+        error: "Script error: CPU limit exceeded",
+      });
+    }, 0);
+    const result = await monitorConsole(api, BASE_OPTS);
+    expect(result.sawErrorLog).toBe(true);
+    expect(result.sawTraceback).toBe(false);
+  });
+
+  it("returns sawWarningLog=true when a warn log line arrives", async () => {
+    const api = buildMockApi({ ticks: [100, 101, 102, 103] });
+    setTimeout(() => {
+      api._fireConsole({
+        messages: {
+          log: ["<font color='orange'>low energy</font>"],
+          results: [],
+        },
+        error: null,
+      });
+    }, 0);
+    const result = await monitorConsole(api, BASE_OPTS);
+    expect(result.sawWarningLog).toBe(true);
+  });
+
+  it("logs progress via core.info at monitorInterval boundaries when logToFile=true", async () => {
+    // ticks: start=100, then 101,102(interval),103(done at delta=3)
+    const api = buildMockApi({ ticks: [100, 100, 101, 102, 103] });
+    await monitorConsole(api, {
+      ...BASE_OPTS,
+      logToFile: true,
+      monitorInterval: 2,
+    });
+    // Progress should be logged when elapsed reaches 2
+    const infoCalls = core.info.mock.calls.map((c) => c[0]);
+    expect(infoCalls.some((m) => m.includes("2/3"))).toBe(true);
+  });
+
+  it("calls api.socket.disconnect() even if an error occurs during polling", async () => {
+    const api = buildMockApi({ ticks: [100] });
+    // Make time() reject after first call
+    let calls = 0;
+    api.time = vi.fn().mockImplementation(() => {
+      calls++;
+      if (calls > 1) return Promise.reject(new Error("network error"));
+      return Promise.resolve({ time: 100 });
+    });
+    await expect(monitorConsole(api, BASE_OPTS)).rejects.toThrow(
+      "network error",
+    );
+    expect(api.socket.disconnect).toHaveBeenCalledTimes(1);
+  });
+
+  it("exits early if a traceback occurs and onTraceback='fail'", async () => {
+    // startTick=100, monitor=10 ticks.
+    // If it didn't exit early, it would call api.time() many times.
+    const api = buildMockApi({
+      ticks: [100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110],
+    });
+
+    // Fire a traceback event after the first poll
+    setTimeout(() => {
+      api._fireConsole({
+        messages: { log: [], results: [] },
+        error:
+          "TypeError: fail-fast test\n    at Object.<anonymous> (main:1:1)",
+      });
+    }, 100);
+
+    const result = await monitorConsole(api, {
+      ...BASE_OPTS,
+      monitor: 10,
+      onTraceback: "fail",
+    });
+
+    expect(result.sawTraceback).toBe(true);
+    // We expect it to have called api.time fewer than 10 times (excluding the startTick call)
+    expect(api.time.mock.calls.length).toBeLessThan(10);
+  });
+
+  it("detects encoded tracebacks in log lines", async () => {
+    const api = buildMockApi({ ticks: [100, 101, 102] });
+    setTimeout(() => {
+      api._fireConsole({
+        messages: {
+          log: [
+            "Error: ReferenceError: a is not defined%0A    at eval (eval at <anonymous> (_console1778948572008_0:1:46), <anonymous>:1:1)%0A    at _console1778948572008_0:1:46",
+          ],
+          results: [],
+        },
+        error: null,
+      });
+    }, 50);
+
+    const result = await monitorConsole(api, {
+      ...BASE_OPTS,
+      onTraceback: "fail",
+    });
+    expect(result.sawTraceback).toBe(true);
+    expect(result.sawErrorLog).toBe(true);
+  });
+});