@gtkx/vitest 2.0.0-beta.1 → 2.0.0-beta.10

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@gtkx/vitest",
-  "version": "2.0.0-beta.1",
-  "description": "Vitest plugin for GTK apps with headless Wayland isolation.",
+  "version": "2.0.0-beta.10",
+  "description": "Vitest plugin for GTKX GNOME apps with headless Wayland isolation.",
   "keywords": [
     "gtkx",
     "gtk",
     "gtk4",
+    "adwaita",
+    "gnome",
     "vitest",
     "testing",
     "plugin",
@@ -32,6 +34,12 @@
       "import": "./dist/index.js",
       "require": null,
       "default": "./dist/index.js"
+    },
+    "./headless": {
+      "types": "./dist/headless.d.ts",
+      "import": "./dist/headless.js",
+      "require": null,
+      "default": "./dist/headless.js"
     }
   },
   "sideEffects": false,
@@ -53,15 +61,15 @@
     "node": ">=26.7.0"
   },
   "dependencies": {
-    "@gtkx/config": "2.0.0-beta.1",
-    "@gtkx/utils": "2.0.0-beta.1",
+    "@gtkx/config": "2.0.0-beta.10",
+    "@gtkx/utils": "2.0.0-beta.10",
     "@homebridge/dbus-native": "^0.7.9"
   },
   "devDependencies": {
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.0"
   },
   "peerDependencies": {
-    "vitest": ">=4"
+    "vitest": ">=5"
   },
   "scripts": {
     "release": "tsx ../../scripts/release-package.ts"

package/src/headless-config.ts

@@ -0,0 +1,61 @@
+const BUS_CONFIG_DOCTYPE =
+    '<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN" ' +
+    '"https://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">';
+
+const HEADLESS_RUNTIME_MARKER = ".gtkx-headless-runtime";
+
+const SWAY_CONFIG_LINES = [
+    /^xwayland disable$/,
+    /^default_border none$/,
+    /^default_floating_border none$/,
+    /^output HEADLESS-1 resolution [1-9]\d*x[1-9]\d*$/,
+    /^output HEADLESS-1 bg #000000 solid_color$/,
+    /^for_window \[app_id="\.\*"\] floating enable, border none$/,
+    /^for_window \[title="\.\*"\] floating enable, border none$/,
+    /^$/,
+];
+
+const createSwayConfig = (width: string, height: string): string =>
+    [
+        "xwayland disable",
+        "default_border none",
+        "default_floating_border none",
+        `output HEADLESS-1 resolution ${width}x${height}`,
+        "output HEADLESS-1 bg #000000 solid_color",
+        'for_window [app_id=".*"] floating enable, border none',
+        'for_window [title=".*"] floating enable, border none',
+        "",
+    ].join("\n");
+
+const createBusConfig = (busSocketPath: string): string =>
+    [
+        BUS_CONFIG_DOCTYPE,
+        "<busconfig>",
+        "  <type>session</type>",
+        `  <listen>unix:path=${busSocketPath}</listen>`,
+        "  <auth>EXTERNAL</auth>",
+        '  <policy context="default">',
+        '    <allow send_destination="*" eavesdrop="true"/>',
+        '    <allow eavesdrop="true"/>',
+        '    <allow own="*"/>',
+        "  </policy>",
+        "</busconfig>",
+    ].join("\n");
+
+const createHeadlessRuntimeMarker = (runtimeDir: string): string =>
+    ["gtkx-headless-runtime-v1", `runtime=${runtimeDir}`, ""].join("\n");
+
+const isSwayConfig = (value: string): boolean => {
+    const lines = value.split("\n");
+
+    return lines.length === SWAY_CONFIG_LINES.length &&
+        SWAY_CONFIG_LINES.every((pattern, index) => pattern.test(lines[index] ?? "invalid"));
+};
+
+export {
+    createBusConfig,
+    createHeadlessRuntimeMarker,
+    createSwayConfig,
+    HEADLESS_RUNTIME_MARKER,
+    isSwayConfig,
+};

package/src/headless-display.ts

@@ -1,9 +1,20 @@
-import { resolveExecutable, spawnWithParentDeathSignal } from "@gtkx/utils";
+import {
+    isProcessAlive,
+    resolveExecutable,
+    spawnWithParentDeathSignal,
+    spawnWithParentDeathSupervisor,
+} from "@gtkx/utils";
 import { type ChildProcess, spawnSync } from "node:child_process";
-import { chmodSync, createWriteStream, existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { Socket } from "node:net";
+import { chmodSync, closeSync, existsSync, mkdtempSync, openSync, rmSync, writeFileSync, writeSync } from "node:fs";
+import { connect, Socket } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import {
+    createBusConfig,
+    createHeadlessRuntimeMarker,
+    createSwayConfig,
+    HEADLESS_RUNTIME_MARKER,
+} from "./headless-config.ts";
 import { startNotificationService } from "./notification-service.ts";
 import { startVirtualSeat } from "./virtual-seat.ts";
 
@@ -42,13 +53,13 @@ type ChildMonitor = {
     path: string;
     read: () => string;
     failure: () => string | undefined;
+    isRunning: () => boolean;
     subscribe: (notify: (failure: string) => void) => () => void;
     stop: () => void;
 };
 
-type WaitForSocketOptions = {
-    monitor: ChildMonitor;
-    guards?: ChildMonitor[];
+type WaitForSocketsOptions = {
+    monitors: ChildMonitor[];
     timeout?: number;
 };
 
@@ -57,18 +68,21 @@ type DisplaySockets = {
     busMonitor: ChildMonitor;
 };
 
-type SocketWatch = {
-    options: WaitForSocketOptions;
+type CapturedStderr = {
+    chunks: string[];
+    logPath: string;
+    stop: () => void;
+};
+
+type SocketsWatch = {
+    options: WaitForSocketsOptions;
     resolve: () => void;
     reject: (error: Error) => void;
 };
 
 const DEFAULT_HEADLESS_SIZE = "1024x768";
 const DEFAULT_HEADLESS_COMPOSITOR: CompositorId = "sway";
-
-const BUS_CONFIG_DOCTYPE =
-    '<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN" ' +
-    '"https://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">';
+const HEADLESS_SIZE_PATTERN = /^[1-9]\d*x[1-9]\d*$/;
 
 const hasWestonFakeSeat = createWestonFakeSeatProbe();
 
@@ -88,19 +102,13 @@ const compositorRegistry: Record<CompositorId, CompositorDescriptor> = {
 
             writeFileSync(
                 configPath,
-                [
-                    "xwayland disable",
-                    "default_border none",
-                    "default_floating_border none",
-                    `output HEADLESS-1 resolution ${width}x${height}`,
-                    "output HEADLESS-1 bg #000000 solid_color",
-                    'for_window [app_id=".*"] floating enable, border none',
-                    'for_window [title=".*"] floating enable, border none',
-                    "",
-                ].join("\n"),
+                createSwayConfig(width, height),
             );
 
-            return spawnWithParentDeathSignal("sway", ["-c", configPath], { stdio: ["ignore", "ignore", "pipe"] });
+            return spawnWithParentDeathSupervisor("sway", ["-c", configPath], {
+                stdio: ["ignore", "ignore", "pipe"],
+                cleanupDirectory: runtimeDir,
+            });
         },
     },
     weston: {
@@ -118,7 +126,7 @@ const compositorRegistry: Record<CompositorId, CompositorDescriptor> = {
                     `--height=${height}`,
                     "--socket=wayland-0",
                 ],
-                { stdio: ["ignore", "ignore", "pipe"] },
+                { stdio: ["ignore", "ignore", "pipe"], cleanupDirectories: [_runtimeDir] },
             ),
     },
 };
@@ -136,10 +144,18 @@ const STATIC_HEADLESS_ENV = {
     ALSOFT_LOGLEVEL: "0",
 };
 
-const resolveHeadlessOptions = (provided: Partial<HeadlessOptions>): HeadlessOptions => ({
-    size: provided.size ?? DEFAULT_HEADLESS_SIZE,
-    compositor: provided.compositor ?? DEFAULT_HEADLESS_COMPOSITOR,
-});
+const resolveHeadlessOptions = (provided: Partial<HeadlessOptions>): HeadlessOptions => {
+    const size = provided.size ?? DEFAULT_HEADLESS_SIZE;
+
+    if (!HEADLESS_SIZE_PATTERN.test(size)) {
+        throw new Error(`Invalid headless display size: ${size}`);
+    }
+
+    return {
+        size,
+        compositor: provided.compositor ?? DEFAULT_HEADLESS_COMPOSITOR,
+    };
+};
 
 const applyEnv = (snapshot: EnvSnapshot, values: Record<string, string>): void => {
     for (const [name, value] of Object.entries(values)) {
@@ -207,26 +223,8 @@ const startCompositor = (runtimeDir: string, options: HeadlessOptions, env: EnvS
 
 const noVirtualSeat = (): void => undefined;
 
-const attachVirtualSeat = (compositor: SpawnedCompositor, socketPath: string): Promise<() => void> =>
-    compositor.requiresVirtualSeat ? startVirtualSeat(socketPath) : Promise.resolve(noVirtualSeat);
-
 const writeBusConfig = (busConfigPath: string, busSocketPath: string): void => {
-    writeFileSync(
-        busConfigPath,
-        [
-            BUS_CONFIG_DOCTYPE,
-            "<busconfig>",
-            "  <type>session</type>",
-            `  <listen>unix:path=${busSocketPath}</listen>`,
-            "  <auth>EXTERNAL</auth>",
-            '  <policy context="default">',
-            '    <allow send_destination="*" eavesdrop="true"/>',
-            '    <allow eavesdrop="true"/>',
-            '    <allow own="*"/>',
-            "  </policy>",
-            "</busconfig>",
-        ].join("\n"),
-    );
+    writeFileSync(busConfigPath, createBusConfig(busSocketPath));
 };
 
 const exitedMessage = (label: string, path: string, code: number | null, signal: NodeJS.Signals | null): string =>
@@ -266,6 +264,7 @@ const monitorChild = (child: ChildProcess, label: string, path: string): ChildMo
         path,
         read: () => log,
         failure: () => failure,
+        isRunning: () => child.exitCode === null && child.signalCode === null && isProcessAlive(child.pid),
         subscribe: (notify) => {
             subscribers.add(notify);
 
@@ -292,12 +291,13 @@ const runCleanups = (cleanups: (() => void)[]): void => {
     cleanups.length = 0;
 };
 
-const pollForPath = (path: string, onFound: () => void): NodeJS.Timeout =>
-    setInterval(() => {
-        if (existsSync(path)) {
-            onFound();
-        }
-    }, 50);
+const isMonitorReady = (monitor: ChildMonitor): boolean => monitor.isRunning() && existsSync(monitor.path);
+
+const pendingMonitors = (monitors: ChildMonitor[]): ChildMonitor[] =>
+    monitors.filter((monitor) => !isMonitorReady(monitor));
+
+const isEveryMonitorReady = (monitors: ChildMonitor[]): boolean =>
+    monitors.every((monitor) => isMonitorReady(monitor));
 
 const firstFailure = (monitors: ChildMonitor[]): string | undefined => {
     for (const monitor of monitors) {
@@ -311,10 +311,15 @@ const firstFailure = (monitors: ChildMonitor[]): string | undefined => {
     return undefined;
 };
 
-const watchForSocket = ({ options, resolve, reject }: SocketWatch): void => {
-    const { monitor, guards = [], timeout = 15_000 } = options;
-    const watched = [monitor, ...guards];
-    const cleanups: (() => void)[] = [monitor.stop];
+const SOCKET_TIMEOUT_MS = 15_000;
+
+const missingMessage = (pending: ChildMonitor[], timeout: number): string =>
+    `${pending.map((monitor) => monitor.label).join(", ")} did not become available within ${String(timeout)}ms\n` +
+    pending.map((monitor) => monitor.read()).join("");
+
+const watchForSockets = ({ options, resolve, reject }: SocketsWatch): void => {
+    const { monitors, timeout = SOCKET_TIMEOUT_MS } = options;
+    const cleanups: (() => void)[] = monitors.map((monitor) => monitor.stop);
 
     const stop = (): void => {
         runCleanups(cleanups);
@@ -322,15 +327,10 @@ const watchForSocket = ({ options, resolve, reject }: SocketWatch): void => {
 
     const fail = (message: string): void => {
         stop();
-
-        for (const guard of guards) {
-            guard.stop();
-        }
-
         reject(new Error(message));
     };
 
-    const alreadyFailed = firstFailure(watched);
+    const alreadyFailed = firstFailure(monitors);
 
     if (alreadyFailed !== undefined) {
         fail(alreadyFailed);
@@ -338,13 +338,25 @@ const watchForSocket = ({ options, resolve, reject }: SocketWatch): void => {
         return;
     }
 
-    const poll = pollForPath(monitor.path, () => {
+    const settle = (): void => {
         stop();
         resolve();
-    });
+    };
+
+    if (isEveryMonitorReady(monitors)) {
+        settle();
+
+        return;
+    }
+
+    const poll = setInterval(() => {
+        if (isEveryMonitorReady(monitors)) {
+            settle();
+        }
+    }, 10);
 
     const timer = setTimeout(() => {
-        fail(`${monitor.label} did not become available within ${String(timeout)}ms\n${monitor.read()}`);
+        fail(missingMessage(pendingMonitors(monitors), timeout));
     }, timeout);
 
     cleanups.push(
@@ -352,44 +364,65 @@ const watchForSocket = ({ options, resolve, reject }: SocketWatch): void => {
             clearInterval(poll);
             clearTimeout(timer);
         },
-        ...watched.map((entry) => entry.subscribe(fail)),
+        ...monitors.map((monitor) => monitor.subscribe(fail)),
     );
 };
 
-const waitForSocket = (options: WaitForSocketOptions): Promise<void> =>
+const waitForSockets = (options: WaitForSocketsOptions): Promise<void> =>
     new Promise((resolve, reject) => {
-        watchForSocket({ options, resolve, reject });
+        watchForSockets({ options, resolve, reject });
     });
 
-const captureCompositorStderr = (child: ChildProcess, logPath: string): string[] => {
+const captureCompositorStderr = (child: ChildProcess, logPath: string): CapturedStderr => {
     const captured: string[] = [];
     const stderr = child.stderr;
 
-    if (stderr !== null) {
-        stderr.setEncoding("utf8");
-        const logStream = createWriteStream(logPath);
-        logStream.on("error", (): void => undefined);
-
-        stderr.on("data", (chunk: string) => {
-            captured.push(chunk);
-            logStream.write(chunk);
-        });
+    if (stderr === null) {
+        return { chunks: captured, logPath, stop: noVirtualSeat };
     }
 
-    return captured;
+    stderr.setEncoding("utf8");
+    const descriptor = openSync(logPath, "a");
+    let isOpen = true;
+
+    const onData = (chunk: string): void => {
+        captured.push(chunk);
+
+        try {
+            writeSync(descriptor, chunk);
+        } catch {
+            return;
+        }
+    };
+
+    stderr.on("data", onData);
+
+    return {
+        chunks: captured,
+        logPath,
+        stop: () => {
+            stderr.removeListener("data", onData);
+
+            if (isOpen) {
+                isOpen = false;
+                closeSync(descriptor);
+            }
+        },
+    };
 };
 
 const compositorExitMessage = (
     code: number | null,
     signal: NodeJS.Signals | null,
-    capturedStderr: string[],
+    captured: CapturedStderr,
 ): string =>
     `[gtkx] the headless compositor exited (code ${String(code)}, signal ${signal ?? "null"}); ` +
-    `every Wayland client in this worker has been severed.\n${capturedStderr.join("")}`;
+    "every Wayland client in this worker has been severed. " +
+    `Its stderr log is kept at ${captured.logPath} until this worker exits.\n${captured.chunks.join("")}`;
 
-const watchCompositorExit = (child: ChildProcess, capturedStderr: string[]): (() => void) => {
+const watchCompositorExit = (child: ChildProcess, captured: CapturedStderr): (() => void) => {
     const report = (code: number | null, signal: NodeJS.Signals | null): void => {
-        process.stderr.write(compositorExitMessage(code, signal, capturedStderr));
+        process.stderr.write(compositorExitMessage(code, signal, captured));
     };
 
     child.on("exit", report);
@@ -397,9 +430,63 @@ const watchCompositorExit = (child: ChildProcess, capturedStderr: string[]): (()
     return () => child.removeListener("exit", report);
 };
 
-const waitForDisplaySockets = async ({ compositorMonitor, busMonitor }: DisplaySockets): Promise<void> => {
-    await waitForSocket({ monitor: busMonitor, guards: [compositorMonitor] });
-    await waitForSocket({ monitor: compositorMonitor });
+const waitForDisplaySockets = ({ compositorMonitor, busMonitor }: DisplaySockets): Promise<void> =>
+    waitForSockets({ monitors: [busMonitor, compositorMonitor] });
+
+const CONNECT_RETRY_MS = 10;
+
+const pause = (duration: number): Promise<void> =>
+    new Promise((resolve) => {
+        setTimeout(resolve, duration);
+    });
+
+const connectFailure = (path: string): Promise<Error | undefined> =>
+    new Promise((resolve) => {
+        const socket = connect(path);
+
+        socket.once("connect", () => {
+            socket.destroy();
+            resolve(undefined);
+        });
+
+        socket.once("error", (cause: Error) => {
+            socket.destroy();
+            resolve(cause);
+        });
+    });
+
+const unreachableMessage = (monitor: ChildMonitor, cause: Error): string =>
+    `${monitor.label} did not accept a connection on ${monitor.path}: ${cause.message}\n${monitor.read()}`;
+
+const waitUntilConnectable = async (monitor: ChildMonitor): Promise<void> => {
+    const deadline = Date.now() + SOCKET_TIMEOUT_MS;
+
+    for (;;) {
+        const failure = await connectFailure(monitor.path);
+
+        if (failure === undefined) {
+            return;
+        }
+
+        if (!monitor.isRunning() || Date.now() >= deadline) {
+            throw new Error(unreachableMessage(monitor, failure));
+        }
+
+        await pause(CONNECT_RETRY_MS);
+    }
+};
+
+const attachCompositorClient = async (
+    compositor: SpawnedCompositor,
+    monitor: ChildMonitor,
+): Promise<() => void> => {
+    if (compositor.requiresVirtualSeat) {
+        return startVirtualSeat(monitor.path);
+    }
+
+    await waitUntilConnectable(monitor);
+
+    return noVirtualSeat;
 };
 
 const killSpawned = (children: ChildProcess[]): void => {
@@ -421,10 +508,25 @@ const makeTeardown = (stops: (() => void)[]): (() => void) => {
     };
 };
 
+const createHeadlessRuntimeDirectory = (): string => {
+    const runtimeDir = mkdtempSync(join(tmpdir(), "gtkx-xdg-"));
+
+    try {
+        chmodSync(runtimeDir, 0o700);
+        const markerPath = join(runtimeDir, HEADLESS_RUNTIME_MARKER);
+        writeFileSync(markerPath, createHeadlessRuntimeMarker(runtimeDir), { flag: "wx", mode: 0o600 });
+        chmodSync(markerPath, 0o600);
+
+        return runtimeDir;
+    } catch (error) {
+        rmSync(runtimeDir, { recursive: true, force: true });
+        throw error;
+    }
+};
+
 const startHeadlessDisplay = async (options: HeadlessOptions): Promise<() => void> => {
     const env: EnvSnapshot = {};
-    const runtimeDir = mkdtempSync(join(tmpdir(), "gtkx-xdg-"));
-    chmodSync(runtimeDir, 0o700);
+    const runtimeDir = createHeadlessRuntimeDirectory();
     const spawned: ChildProcess[] = [];
 
     const removeRuntime = (): void => {
@@ -433,6 +535,7 @@ const startHeadlessDisplay = async (options: HeadlessOptions): Promise<() => voi
     };
 
     try {
+        applyEnv(env, STATIC_HEADLESS_ENV);
         applyEnv(env, { XDG_RUNTIME_DIR: runtimeDir });
         const busConfigPath = join(runtimeDir, "session.conf");
         const busSocketPath = join(runtimeDir, "bus");
@@ -440,6 +543,7 @@ const startHeadlessDisplay = async (options: HeadlessOptions): Promise<() => voi
 
         const busChild = spawnWithParentDeathSignal("dbus-daemon", [`--config-file=${busConfigPath}`], {
             stdio: ["ignore", "ignore", "pipe"],
+            cleanupDirectories: [runtimeDir],
         });
 
         busChild.unref();
@@ -453,13 +557,14 @@ const startHeadlessDisplay = async (options: HeadlessOptions): Promise<() => voi
         const compositorMonitor = monitorChild(compositor.child, "Compositor", compositorSocketPath);
         applyEnv(env, { WAYLAND_DISPLAY: compositor.socket });
         await waitForDisplaySockets({ compositorMonitor, busMonitor });
-        const stopVirtualSeat = await attachVirtualSeat(compositor, compositorSocketPath);
+        const stopVirtualSeat = await attachCompositorClient(compositor, compositorMonitor);
         const stopNotifications = await startNotificationService(`unix:path=${busSocketPath}`);
         const capturedStderr = captureCompositorStderr(compositor.child, join(runtimeDir, "compositor.stderr.log"));
         const stopExitWatch = watchCompositorExit(compositor.child, capturedStderr);
 
         return makeTeardown([
             stopExitWatch,
+            capturedStderr.stop,
             () => {
                 killSpawned(spawned);
             },

package/src/headless.ts

@@ -0,0 +1,14 @@
+export {
+    readHeadlessOptions,
+    resolveHeadlessOptions,
+    startHeadlessDisplay,
+    STATIC_HEADLESS_ENV,
+    type CompositorId,
+    type HeadlessOptions,
+} from "./headless-display.js";
+export {
+    findStaleHeadlessDisplays,
+    reapStaleHeadlessDisplays,
+    reapStaleHeadlessDisplaysAtStartup,
+    type StaleHeadlessDisplay,
+} from "./reap-headless-displays.js";

package/src/index.ts

@@ -1,15 +1,17 @@
 import type { Plugin } from "vitest/config";
+import { assertSupportedNodeVersion, createConfigLoader } from "@gtkx/config/internal";
 import createConfigPlugin from "@gtkx/config/vite-plugin";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { type HeadlessOptions, STATIC_HEADLESS_ENV } from "./headless-display.ts";
+import { reapStaleHeadlessDisplaysAtStartup } from "./reap-headless-displays.ts";
 
 /**
  * Options accepted by the GTKX Vitest plugin. Every headless display
  * setting is optional and falls back to a built-in default when omitted.
  */
-type PluginOptions = Partial<HeadlessOptions>;
+type PluginOptions = Partial<HeadlessOptions> & Partial<Record<"configFile", string | undefined>>;
 
 const GTKX_INLINE_DEPS: RegExp[] = [/@gtkx\/(?!native)/, /[/\\]\.gtkx[/\\]/];
 const DEFAULT_TIMEOUT = 30_000;
@@ -21,7 +23,7 @@ const workerPreloadUrl = (): URL => {
     return pathToFileURL(path);
 };
 
-const headlessPreloadSpecifier = (options: PluginOptions): string => {
+const headlessPreloadSpecifier = (options: Partial<HeadlessOptions>): string => {
     const url = workerPreloadUrl();
 
     for (const [key, value] of Object.entries(options)) {
@@ -36,17 +38,29 @@ const headlessPreloadSpecifier = (options: PluginOptions): string => {
  * Wayland display. It configures the forks pool, injects the worker preload and
  * setup files, and sets the environment needed for headless GTK4 rendering.
  *
+ * Each worker's compositor, session bus, and private runtime directory are torn
+ * down when the worker exits, and a guard process tears them down as well when
+ * the worker or the Vitest process that launched it is killed with `SIGKILL`.
+ * Creating the plugin reaps stale `gtkx-xdg-*` runtime directories left behind
+ * by earlier runs, which `gtkx cleanup` also does on demand.
+ *
  * @param options Headless display settings (size, compositor) forwarded to each worker.
  * @returns A Vitest config plugin.
  */
-const gtkx = (options: PluginOptions = {}): Plugin =>
-    createConfigPlugin({
+const gtkx = (options: PluginOptions = {}): Plugin => {
+    assertSupportedNodeVersion();
+    reapStaleHeadlessDisplaysAtStartup();
+    const { configFile, ...headlessOptions } = options;
+    const loadConfig = createConfigLoader({ configFile });
+
+    return createConfigPlugin({
         name: "gtkx:vitest",
+        loadConfig,
         config(config) {
             return {
                 test: {
                     globals: true,
-                    execArgv: ["--disable-sigusr1", "--import", headlessPreloadSpecifier(options)],
+                    execArgv: ["--disable-sigusr1", "--import", headlessPreloadSpecifier(headlessOptions)],
                     testTimeout: config.test?.testTimeout ?? DEFAULT_TIMEOUT,
                     hookTimeout: config.test?.hookTimeout ?? DEFAULT_TIMEOUT,
                     pool: "forks",
@@ -60,6 +74,7 @@ const gtkx = (options: PluginOptions = {}): Plugin =>
             };
         },
     });
+};
 
 export default gtkx;
 export { type CompositorId, type HeadlessOptions } from "./headless-display.ts";