factorio-test-cli 2.0.1 → 3.0.0

package/README.md

@@ -9,3 +9,60 @@ If using an npm package, you can install `factorio-test-cli` to your dev depende
 ```bash
 npm install --save-dev factorio-test-cli
 ```
+
+## Configuration Architecture
+
+### Config Categories
+
+| Category | Casing | Location | Example Fields |
+|----------|--------|----------|----------------|
+| CLI-only | camelCase | `cli-config.ts` | `config`, `graphics`, `watch` |
+| File+CLI | camelCase | `cli-config.ts` | `modPath`, `factorioPath`, `verbose`, `forbidOnly` |
+| Test | snake_case | `types/config.d.ts` | `test_pattern`, `game_speed`, `bail` |
+
+- **CLI-only**: Options only available via command line, not in config files
+- **File+CLI**: Options that can be set in `factorio-test.json` or via command line (CLI overrides file)
+- **Test**: Runner configuration passed to the Factorio mod; uses snake_case for Lua compatibility
+
+### Type Hierarchy
+
+```
+types/config.d.ts
+└── TestRunnerConfig        # CLI-passable fields (source of truth)
+        │
+        ├── Extended by: FactorioTest.Config (types/index.d.ts)
+        │                 └── Adds mod-only fields: default_ticks_between_tests,
+        │                     before_test_run, after_test_run, sound_effects
+        │
+        └── Validated by: testRunnerConfigSchema (cli/config/test-config.ts)
+                          └── Zod schema for runtime validation
+```
+
+### Data Flow
+
+```
+CLI args ─────────────────┐
+                          ▼
+factorio-test.json ──► loadConfig() ──► mergeCliConfig() ──► RunOptions
+                                              │
+                                              ▼
+                                        buildTestConfig() ──► TestRunnerConfig ──► Factorio mod
+```
+
+1. `loadConfig()` reads `factorio-test.json` (or `package.json["factorio-test"]`)
+2. `mergeCliConfig()` merges file config with CLI options (CLI wins)
+3. `buildTestConfig()` extracts test runner options, combining patterns with OR logic
+
+### File Organization
+
+```
+types/
+├── config.d.ts       # TestRunnerConfig interface (source of truth for CLI-passable test options)
+└── index.d.ts        # FactorioTest.Config extends TestRunnerConfig with mod-only fields
+
+cli/config/
+├── index.ts          # Re-exports all public APIs
+├── test-config.ts    # Zod schema validating TestRunnerConfig + CLI registration
+├── cli-config.ts     # CliConfig + CliOnlyOptions schemas + CLI registration
+└── loader.ts         # Config loading, path resolution, merging, RunOptions type
+```

package/cli-error.js

@@ -0,0 +1,6 @@
+export class CliError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "CliError";
+    }
+}

package/cli.js

@@ -1,10 +1,21 @@
 #!/usr/bin/env node
 import { program } from "commander";
+import chalk from "chalk";
+import { CliError } from "./cli-error.js";
 import "./run.js";
-await program
-    .name("factorio-test")
-    .description("cli for factorio testing")
-    .helpCommand(true)
-    .showHelpAfterError()
-    .showSuggestionAfterError()
-    .parseAsync();
+try {
+    await program
+        .name("factorio-test")
+        .description("cli for factorio testing")
+        .helpCommand(true)
+        .showHelpAfterError()
+        .showSuggestionAfterError()
+        .parseAsync();
+}
+catch (error) {
+    if (error instanceof CliError) {
+        console.error(chalk.red("Error:"), error.message);
+        process.exit(1);
+    }
+    throw error;
+}

package/config.test.js

@@ -0,0 +1,94 @@
+import { describe, it, expect, beforeEach, afterEach, assertType } from "vitest";
+import * as fs from "fs";
+import * as path from "path";
+import { loadConfig, mergeTestConfig, buildTestConfig } from "./config/index.js";
+const testDir = path.join(import.meta.dirname, "__test_fixtures__");
+describe("loadConfig", () => {
+    beforeEach(() => {
+        fs.mkdirSync(testDir, { recursive: true });
+    });
+    afterEach(() => {
+        fs.rmSync(testDir, { recursive: true, force: true });
+    });
+    it("returns empty object when no config exists", () => {
+        expect(loadConfig(path.join(testDir, "nonexistent.json"))).toEqual({});
+    });
+    it("loads factorio-test.json with snake_case test config", () => {
+        const configPath = path.join(testDir, "factorio-test.json");
+        fs.writeFileSync(configPath, JSON.stringify({
+            modPath: "./test",
+            test: { game_speed: 100 },
+        }));
+        expect(loadConfig(configPath)).toMatchObject({
+            modPath: path.join(testDir, "test"),
+            test: { game_speed: 100 },
+        });
+    });
+    it("throws on invalid keys", () => {
+        const configPath = path.join(testDir, "bad.json");
+        fs.writeFileSync(configPath, JSON.stringify({ test: { invalid_key: true } }));
+        expect(() => loadConfig(configPath)).toThrow();
+    });
+    it("error message includes file path for invalid top-level key", () => {
+        const configPath = path.join(testDir, "bad-toplevel.json");
+        fs.writeFileSync(configPath, JSON.stringify({ unknownKey: true }));
+        expect(() => loadConfig(configPath)).toThrow(configPath);
+    });
+    it("error message includes field name for invalid top-level key", () => {
+        const configPath = path.join(testDir, "bad-toplevel.json");
+        fs.writeFileSync(configPath, JSON.stringify({ unknownKey: true }));
+        expect(() => loadConfig(configPath)).toThrow(/unknownKey/);
+    });
+    it("error message includes field path for invalid nested key", () => {
+        const configPath = path.join(testDir, "bad-nested.json");
+        fs.writeFileSync(configPath, JSON.stringify({ test: { badNestedKey: true } }));
+        expect(() => loadConfig(configPath)).toThrow(/test/);
+    });
+    it("error message includes field name for type mismatch", () => {
+        const configPath = path.join(testDir, "bad-type.json");
+        fs.writeFileSync(configPath, JSON.stringify({ test: { game_speed: "fast" } }));
+        expect(() => loadConfig(configPath)).toThrow(/game_speed/);
+    });
+});
+describe("TestRunnerConfig type compatibility", () => {
+    it("all TestRunnerConfig keys exist in FactorioTest.Config with compatible types", () => {
+        assertType({});
+    });
+});
+describe("mergeTestConfig", () => {
+    it("CLI options override config file", () => {
+        const result = mergeTestConfig({ game_speed: 100 }, { game_speed: 200 });
+        expect(result.game_speed).toBe(200);
+    });
+    it("CLI test pattern overrides config file", () => {
+        const result = mergeTestConfig({ test_pattern: "foo" }, { test_pattern: "bar" });
+        expect(result.test_pattern).toBe("bar");
+    });
+    it("preserves config file values when CLI undefined", () => {
+        const result = mergeTestConfig({ game_speed: 100, log_passed_tests: true }, {});
+        expect(result.game_speed).toBe(100);
+        expect(result.log_passed_tests).toBe(true);
+    });
+});
+describe("buildTestConfig test pattern priority", () => {
+    const baseOptions = { dataDirectory: "." };
+    it("positional patterns override CLI option and config file", () => {
+        const result = buildTestConfig({ test: { test_pattern: "config" } }, { ...baseOptions, testPattern: "cli" }, [
+            "pos1",
+            "pos2",
+        ]);
+        expect(result.test_pattern).toBe("(pos1)|(pos2)");
+    });
+    it("CLI option overrides config file when no positional patterns", () => {
+        const result = buildTestConfig({ test: { test_pattern: "config" } }, { ...baseOptions, testPattern: "cli" }, []);
+        expect(result.test_pattern).toBe("cli");
+    });
+    it("uses config file when no CLI option or positional patterns", () => {
+        const result = buildTestConfig({ test: { test_pattern: "config" } }, baseOptions, []);
+        expect(result.test_pattern).toBe("config");
+    });
+    it("undefined when no patterns specified anywhere", () => {
+        const result = buildTestConfig({}, baseOptions, []);
+        expect(result.test_pattern).toBeUndefined();
+    });
+});

package/factorio-discovery.js

@@ -0,0 +1,53 @@
+import * as os from "os";
+import * as fs from "fs";
+import * as path from "path";
+import { spawnSync } from "child_process";
+import { CliError } from "./cli-error.js";
+export function getFactorioPlayerDataPath() {
+    const platform = os.platform();
+    if (platform === "win32") {
+        return path.join(process.env.APPDATA, "Factorio", "player-data.json");
+    }
+    if (platform === "darwin") {
+        return path.join(os.homedir(), "Library", "Application Support", "factorio", "player-data.json");
+    }
+    return path.join(os.homedir(), ".factorio", "player-data.json");
+}
+function factorioIsInPath() {
+    const result = spawnSync("factorio", ["--version"], { stdio: "ignore" });
+    return result.status === 0;
+}
+export function autoDetectFactorioPath() {
+    if (factorioIsInPath()) {
+        return "factorio";
+    }
+    let pathsToTry;
+    if (os.platform() === "linux" || os.platform() === "darwin") {
+        pathsToTry = [
+            "~/.local/share/Steam/steamapps/common/Factorio/bin/x64/factorio",
+            "~/Library/Application Support/Steam/steamapps/common/Factorio/factorio.app/Contents/MacOS/factorio",
+            "~/.factorio/bin/x64/factorio",
+            "/Applications/factorio.app/Contents/MacOS/factorio",
+            "/usr/share/factorio/bin/x64/factorio",
+            "/usr/share/games/factorio/bin/x64/factorio",
+        ];
+    }
+    else if (os.platform() === "win32") {
+        pathsToTry = [
+            "factorio.exe",
+            process.env["ProgramFiles(x86)"] + "\\Steam\\steamapps\\common\\Factorio\\bin\\x64\\factorio.exe",
+            process.env["ProgramFiles"] + "\\Factorio\\bin\\x64\\factorio.exe",
+        ];
+    }
+    else {
+        throw new CliError(`Cannot auto-detect factorio path on platform ${os.platform()}`);
+    }
+    pathsToTry = pathsToTry.map((p) => p.replace(/^~\//, os.homedir() + "/"));
+    for (const testPath of pathsToTry) {
+        if (fs.statSync(testPath, { throwIfNoEntry: false })?.isFile()) {
+            return path.resolve(testPath);
+        }
+    }
+    throw new CliError(`Could not auto-detect factorio executable. Tried: ${pathsToTry.join(", ")}. ` +
+        "Either add the factorio bin to your path, or specify the path with --factorio-path");
+}

package/factorio-discovery.test.js

@@ -0,0 +1,24 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+vi.mock("child_process", () => ({
+    spawnSync: vi.fn(() => ({ status: 1 })),
+}));
+describe("autoDetectFactorioPath", () => {
+    beforeEach(() => {
+        vi.resetModules();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("returns 'factorio' if in PATH", async () => {
+        const { spawnSync } = await import("child_process");
+        vi.mocked(spawnSync).mockReturnValue({ status: 0 });
+        const { autoDetectFactorioPath } = await import("./factorio-discovery.js");
+        expect(autoDetectFactorioPath()).toBe("factorio");
+    });
+    it("throws if no path found and factorio not in PATH", async () => {
+        const { spawnSync } = await import("child_process");
+        vi.mocked(spawnSync).mockReturnValue({ status: 1 });
+        const { autoDetectFactorioPath } = await import("./factorio-discovery.js");
+        expect(() => autoDetectFactorioPath()).toThrow(/Could not auto-detect/);
+    });
+});

package/factorio-output-parser.js

@@ -0,0 +1,41 @@
+import { EventEmitter } from "events";
+const EVENT_PREFIX = "FACTORIO-TEST-EVENT:";
+export function parseEvent(line) {
+    if (!line.startsWith(EVENT_PREFIX)) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(line.slice(EVENT_PREFIX.length));
+    }
+    catch {
+        return undefined;
+    }
+}
+export class FactorioOutputHandler extends EventEmitter {
+    inMessage = false;
+    handleLine(line) {
+        if (line.startsWith("FACTORIO-TEST-RESULT:")) {
+            this.emit("result", line.slice("FACTORIO-TEST-RESULT:".length));
+            return;
+        }
+        if (line === "FACTORIO-TEST-MESSAGE-START") {
+            this.inMessage = true;
+            return;
+        }
+        if (line === "FACTORIO-TEST-MESSAGE-END") {
+            this.inMessage = false;
+            return;
+        }
+        const event = parseEvent(line);
+        if (event) {
+            this.emit("event", event);
+            return;
+        }
+        if (this.inMessage) {
+            this.emit("message", line);
+        }
+        else {
+            this.emit("log", line);
+        }
+    }
+}

package/factorio-output-parser.test.js

@@ -0,0 +1,38 @@
+import { describe, it, expect } from "vitest";
+import { parseEvent } from "./factorio-output-parser.js";
+describe("parseEvent", () => {
+    it("parses valid testStarted event", () => {
+        const line = 'FACTORIO-TEST-EVENT:{"type":"testStarted","test":{"path":"root > mytest"}}';
+        const result = parseEvent(line);
+        expect(result).toEqual({
+            type: "testStarted",
+            test: { path: "root > mytest" },
+        });
+    });
+    it("parses valid testPassed event with duration", () => {
+        const line = 'FACTORIO-TEST-EVENT:{"type":"testPassed","test":{"path":"root > test","duration":"1.23 ms"}}';
+        const result = parseEvent(line);
+        expect(result).toEqual({
+            type: "testPassed",
+            test: { path: "root > test", duration: "1.23 ms" },
+        });
+    });
+    it("parses testFailed event with errors", () => {
+        const line = 'FACTORIO-TEST-EVENT:{"type":"testFailed","test":{"path":"test"},"errors":["error1","error2"]}';
+        const result = parseEvent(line);
+        expect(result).toEqual({
+            type: "testFailed",
+            test: { path: "test" },
+            errors: ["error1", "error2"],
+        });
+    });
+    it("returns undefined for non-event lines", () => {
+        expect(parseEvent("some random log line")).toBeUndefined();
+        expect(parseEvent("FACTORIO-TEST-MESSAGE-START")).toBeUndefined();
+        expect(parseEvent("")).toBeUndefined();
+    });
+    it("returns undefined for malformed JSON", () => {
+        expect(parseEvent("FACTORIO-TEST-EVENT:{not valid json}")).toBeUndefined();
+        expect(parseEvent("FACTORIO-TEST-EVENT:")).toBeUndefined();
+    });
+});

package/factorio-process.js

@@ -0,0 +1,165 @@
+import { spawn } from "child_process";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import BufferLineSplitter from "./buffer-line-splitter.js";
+import { FactorioOutputHandler } from "./factorio-output-parser.js";
+import { OutputPrinter } from "./output-formatter.js";
+import { ProgressRenderer } from "./progress-renderer.js";
+import { TestRunCollector } from "./test-run-collector.js";
+import { CliError } from "./cli-error.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export function getHeadlessSavePath(overridePath) {
+    if (overridePath) {
+        return path.resolve(overridePath);
+    }
+    return path.join(__dirname, "headless-save.zip");
+}
+export function parseResultMessage(message) {
+    if (message.endsWith(":focused")) {
+        return {
+            status: message.slice(0, -":focused".length),
+            hasFocusedTests: true,
+        };
+    }
+    return {
+        status: message,
+        hasFocusedTests: false,
+    };
+}
+function createOutputComponents(options) {
+    const handler = new FactorioOutputHandler();
+    const collector = new TestRunCollector();
+    const printer = new OutputPrinter({
+        verbose: options.verbose,
+        quiet: options.quiet,
+    });
+    const progress = new ProgressRenderer();
+    handler.on("event", (event) => {
+        collector.handleEvent(event);
+        progress.handleEvent(event);
+        if (options.verbose) {
+            progress.withPermanentOutput(() => console.log(JSON.stringify(event)));
+        }
+    });
+    handler.on("log", (line) => {
+        collector.captureLog(line);
+        progress.withPermanentOutput(() => printer.printVerbose(line));
+    });
+    handler.on("message", (line) => {
+        progress.withPermanentOutput(() => printer.printMessage(line));
+    });
+    collector.on("testFinished", (test) => {
+        progress.handleTestFinished(test);
+        progress.withPermanentOutput(() => printer.printTestResult(test));
+    });
+    return { handler, collector, printer, progress };
+}
+export async function runFactorioTestsHeadless(factorioPath, dataDir, savePath, additionalArgs, options) {
+    const args = [
+        "--benchmark",
+        savePath,
+        "--benchmark-ticks",
+        "1000000000",
+        "--mod-directory",
+        path.join(dataDir, "mods"),
+        "-c",
+        path.join(dataDir, "config.ini"),
+        ...additionalArgs,
+    ];
+    console.log("Running tests (headless)...");
+    const factorioProcess = spawn(factorioPath, args, {
+        stdio: ["inherit", "pipe", "pipe"],
+    });
+    const { handler, collector, printer, progress } = createOutputComponents(options);
+    let resultMessage;
+    let testRunStarted = false;
+    let startupTimedOut = false;
+    let wasCancelled = false;
+    handler.on("result", (msg) => {
+        resultMessage = msg;
+        progress.finish();
+        printer.resetMessage();
+    });
+    handler.on("event", (event) => {
+        if (event.type === "testRunStarted") {
+            testRunStarted = true;
+            clearTimeout(startupTimeout);
+        }
+    });
+    const startupTimeout = setTimeout(() => {
+        if (!testRunStarted) {
+            startupTimedOut = true;
+            factorioProcess.kill();
+        }
+    }, 10_000);
+    const abortHandler = () => {
+        wasCancelled = true;
+        factorioProcess.kill();
+    };
+    options.signal?.addEventListener("abort", abortHandler);
+    new BufferLineSplitter(factorioProcess.stdout).on("line", (line) => handler.handleLine(line));
+    new BufferLineSplitter(factorioProcess.stderr).on("line", (line) => handler.handleLine(line));
+    await new Promise((resolve, reject) => {
+        factorioProcess.on("exit", (code, signal) => {
+            clearTimeout(startupTimeout);
+            options.signal?.removeEventListener("abort", abortHandler);
+            if (wasCancelled) {
+                resolve();
+            }
+            else if (startupTimedOut) {
+                reject(new CliError("Factorio unresponsive: no test run started within 10 seconds"));
+            }
+            else if (resultMessage !== undefined) {
+                resolve();
+            }
+            else {
+                reject(new CliError(`Factorio exited with code ${code}, signal ${signal}, no result received`));
+            }
+        });
+    });
+    if (wasCancelled) {
+        return { status: "cancelled", hasFocusedTests: false };
+    }
+    const parsed = parseResultMessage(resultMessage);
+    return { ...parsed, message: resultMessage, data: collector.getData() };
+}
+export async function runFactorioTestsGraphics(factorioPath, dataDir, savePath, additionalArgs, options) {
+    const args = [
+        "--load-game",
+        savePath,
+        "--mod-directory",
+        path.join(dataDir, "mods"),
+        "-c",
+        path.join(dataDir, "config.ini"),
+        ...additionalArgs,
+    ];
+    console.log("Running tests (graphics)...");
+    const factorioProcess = spawn(factorioPath, args, {
+        stdio: ["inherit", "pipe", "inherit"],
+    });
+    const { handler, collector, printer, progress } = createOutputComponents(options);
+    let resultMessage;
+    let resolvePromise;
+    handler.on("result", (msg) => {
+        resultMessage = msg;
+        progress.finish();
+        printer.resetMessage();
+        if (options.resolveOnResult && resolvePromise) {
+            resolvePromise();
+        }
+    });
+    new BufferLineSplitter(factorioProcess.stdout).on("line", (line) => handler.handleLine(line));
+    await new Promise((resolve, reject) => {
+        resolvePromise = resolve;
+        factorioProcess.on("exit", (code, signal) => {
+            if (resultMessage !== undefined) {
+                resolve();
+            }
+            else {
+                reject(new CliError(`Factorio exited with code ${code}, signal ${signal}`));
+            }
+        });
+    });
+    const parsed = parseResultMessage(resultMessage);
+    return { ...parsed, message: resultMessage, data: collector.getData() };
+}

package/factorio-process.test.js

@@ -0,0 +1,15 @@
+import { describe, it, expect } from "vitest";
+import { parseResultMessage } from "./factorio-process.js";
+describe("parseResultMessage", () => {
+    it.each([
+        ["passed", { status: "passed", hasFocusedTests: false }],
+        ["failed", { status: "failed", hasFocusedTests: false }],
+        ["todo", { status: "todo", hasFocusedTests: false }],
+        ["loadError", { status: "loadError", hasFocusedTests: false }],
+        ["passed:focused", { status: "passed", hasFocusedTests: true }],
+        ["failed:focused", { status: "failed", hasFocusedTests: true }],
+        ["todo:focused", { status: "todo", hasFocusedTests: true }],
+    ])("parses %s", (input, expected) => {
+        expect(parseResultMessage(input)).toEqual(expected);
+    });
+});

package/file-watcher.js

@@ -0,0 +1,36 @@
+import * as fs from "fs";
+import { minimatch } from "minimatch";
+export function matchesPattern(filename, patterns) {
+    const normalizedFilename = filename.replace(/\\/g, "/");
+    return patterns.some((pattern) => minimatch(normalizedFilename, pattern));
+}
+export function watchDirectory(dir, onChange, options) {
+    const debounceMs = options.debounceMs ?? 300;
+    let timeout;
+    const debouncedOnChange = () => {
+        if (timeout)
+            clearTimeout(timeout);
+        timeout = setTimeout(onChange, debounceMs);
+    };
+    const watcher = fs.watch(dir, { recursive: true }, (_, filename) => {
+        if (!filename)
+            return;
+        if (matchesPattern(filename, options.patterns)) {
+            debouncedOnChange();
+        }
+    });
+    return watcher;
+}
+export function watchFile(filePath, onChange, options) {
+    const debounceMs = options?.debounceMs ?? 300;
+    let timeout;
+    const debouncedOnChange = () => {
+        if (timeout)
+            clearTimeout(timeout);
+        timeout = setTimeout(onChange, debounceMs);
+    };
+    const watcher = fs.watch(filePath, () => {
+        debouncedOnChange();
+    });
+    return watcher;
+}

package/file-watcher.test.js

@@ -0,0 +1,29 @@
+import { describe, it, expect } from "vitest";
+import { matchesPattern } from "./file-watcher.js";
+describe("matchesPattern", () => {
+    const defaultPatterns = ["info.json", "**/*.lua"];
+    it.each([
+        ["info.json", defaultPatterns, true],
+        ["control.lua", defaultPatterns, true],
+        ["nested/file.lua", defaultPatterns, true],
+        ["deeply/nested/module.lua", defaultPatterns, true],
+        ["data.ts", defaultPatterns, false],
+        ["settings.json", defaultPatterns, false],
+        ["info.json.bak", defaultPatterns, false],
+        ["some/info.json", defaultPatterns, false],
+    ])("matchesPattern(%j, %j) => %j", (filename, patterns, expected) => {
+        expect(matchesPattern(filename, patterns)).toBe(expected);
+    });
+    it("handles custom patterns", () => {
+        expect(matchesPattern("src/main.ts", ["**/*.ts"])).toBe(true);
+        expect(matchesPattern("main.ts", ["**/*.ts"])).toBe(true);
+        expect(matchesPattern("main.js", ["**/*.ts"])).toBe(false);
+    });
+    it("handles single wildcard", () => {
+        expect(matchesPattern("file.lua", ["*.lua"])).toBe(true);
+        expect(matchesPattern("nested/file.lua", ["*.lua"])).toBe(false);
+    });
+    it("handles backslash paths (Windows)", () => {
+        expect(matchesPattern("nested\\file.lua", defaultPatterns)).toBe(true);
+    });
+});