@voltkit/volt-test 0.1.2

package/dist/fs.js

@@ -0,0 +1,49 @@
+import { basename, join, resolve } from 'node:path';
+import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { setTimeout as delay } from 'node:timers/promises';
+const EXCLUDED_COPY_DIRS = new Set([
+    'dist',
+    'dist-volt',
+    '.turbo',
+    'target',
+    'coverage',
+]);
+export function copyProjectToTemp(projectDir, repoRoot) {
+    const resolvedSource = resolve(projectDir);
+    if (!existsSync(resolvedSource)) {
+        throw new Error(`[volt:test] source project does not exist: ${resolvedSource}`);
+    }
+    const tempRoot = mkdtempSync(join(resolve(repoRoot), '.volt-test-'));
+    const tempProjectDir = join(tempRoot, basename(resolvedSource));
+    cpSync(resolvedSource, tempProjectDir, {
+        recursive: true,
+        force: true,
+        filter: (sourcePath) => {
+            const name = basename(sourcePath);
+            return !EXCLUDED_COPY_DIRS.has(name);
+        },
+    });
+    return { tempRoot, tempProjectDir };
+}
+export async function cleanupDirectoryBestEffort(directoryPath, logger) {
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+        try {
+            rmSync(directoryPath, { recursive: true, force: true });
+            return;
+        }
+        catch (error) {
+            if (attempt === 7) {
+                logger.warn(`[volt:test] cleanup warning for ${directoryPath}: ${error instanceof Error ? error.message : String(error)}`);
+                return;
+            }
+            await delay(250);
+        }
+    }
+}
+export function readTextFile(filePath) {
+    return readFileSync(filePath, 'utf8');
+}
+export function writeTextFile(filePath, contents) {
+    writeFileSync(filePath, contents, 'utf8');
+}
+//# sourceMappingURL=fs.js.map

package/dist/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC/F,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAG3D,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC;IACjC,MAAM;IACN,WAAW;IACX,QAAQ;IACR,QAAQ;IACR,UAAU;CACX,CAAC,CAAC;AAOH,MAAM,UAAU,iBAAiB,CAAC,UAAkB,EAAE,QAAgB;IACpE,MAAM,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3C,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,8CAA8C,cAAc,EAAE,CAAC,CAAC;IAClF,CAAC;IAED,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC;IACrE,MAAM,cAAc,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC;IAEhE,MAAM,CAAC,cAAc,EAAE,cAAc,EAAE;QACrC,SAAS,EAAE,IAAI;QACf,KAAK,EAAE,IAAI;QACX,MAAM,EAAE,CAAC,UAAU,EAAE,EAAE;YACrB,MAAM,IAAI,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;YAClC,OAAO,CAAC,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACvC,CAAC;KACF,CAAC,CAAC;IAEH,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;AACtC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,aAAqB,EAAE,MAAsB;IAC5F,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,CAAC;YACH,MAAM,CAAC,aAAa,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACxD,OAAO;QACT,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;gBAClB,MAAM,CAAC,IAAI,CACT,mCAAmC,aAAa,KAC9C,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CACvD,EAAE,CACH,CAAC;gBACF,OAAO;YACT,CAAC;YACD,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,OAAO,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,QAAgB;IAC9D,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { defineTestConfig, loadVoltTestConfig, validateTestConfig, } from './config.js';
+export { assertWindowReady, parseWindowStatus, waitForWindowStatus, } from './window.js';
+export type { LoadedVoltTestConfig, LoadVoltTestConfigOptions, RunSuitesOptions, VoltTestArtifactCaptureResult, VoltTestConfig, VoltTestLogger, VoltTestSuite, VoltTestSuiteContext, } from './types.js';
+export { runSuites } from './runner.js';
+export { VoltAppLauncher } from './launcher.js';
+export { FileDialogAutomationDriver, MenuAutomationDriver, TrayAutomationDriver, } from './drivers/index.js';
+export { createHelloWorldSmokeSuite, createIpcDemoSmokeSuite, } from './suites/index.js';
+export type { AutomationEvent, FileDialogAutomationDriverOptions, FileDialogAutomationPlatform, MenuAutomationDriverOptions, MenuSetupState, OpenDialogAutomationResult, SaveDialogAutomationResult, TrayAutomationDriverOptions, TraySetupState, } from './drivers/index.js';
+export type { HelloWorldSmokePayload, HelloWorldSmokeSuiteOptions, IpcDemoSmokePayload, IpcDemoSmokeSuiteOptions, } from './suites/index.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export { defineTestConfig, loadVoltTestConfig, validateTestConfig, } from './config.js';
+export { assertWindowReady, parseWindowStatus, waitForWindowStatus, } from './window.js';
+export { runSuites } from './runner.js';
+export { VoltAppLauncher } from './launcher.js';
+export { FileDialogAutomationDriver, MenuAutomationDriver, TrayAutomationDriver, } from './drivers/index.js';
+export { createHelloWorldSmokeSuite, createIpcDemoSmokeSuite, } from './suites/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAWrB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,mBAAmB,CAAC"}

package/dist/launcher.d.ts

@@ -0,0 +1,42 @@
+import type { VoltTestLogger } from './types.js';
+export interface VoltAppLauncherOptions {
+    repoRoot: string;
+    cliEntryPath: string;
+    logger: VoltTestLogger;
+}
+export interface RunScenarioOptions<TPayload> {
+    sourceProjectDir: string;
+    resultFile: string;
+    timeoutMs?: number;
+    prepareProject?: (projectDir: string) => Promise<void> | void;
+    validatePayload?: (payload: unknown) => TPayload;
+    preserveTempDir?: boolean;
+    artifactsDir?: string;
+    logFileName?: string;
+    screenshotFileName?: string;
+    captureScreenshotOnError?: boolean;
+}
+/**
+ * Runs a Volt app scenario in an isolated temp project copy.
+ * The launcher builds the copied project, launches the produced runtime artifact,
+ * waits for a JSON result file, validates the payload, and enforces process cleanup.
+ */
+export declare class VoltAppLauncher {
+    private readonly repoRoot;
+    private readonly cliEntryPath;
+    private readonly logger;
+    constructor(options: VoltAppLauncherOptions);
+    /**
+     * Execute one scenario and return its validated payload.
+     * Set `preserveTempDir` when debugging to inspect generated temp artifacts.
+     */
+    run<TPayload = unknown>(options: RunScenarioOptions<TPayload>): Promise<TPayload>;
+    private ensureCliEntry;
+    private buildProject;
+    private launchBinary;
+}
+declare function resolveRuntimeBinary(projectDir: string): string;
+export declare const __testOnly: {
+    resolveRuntimeBinary: typeof resolveRuntimeBinary;
+};
+export {};

package/dist/launcher.js

@@ -0,0 +1,172 @@
+import { execFileSync, spawn } from 'node:child_process';
+import { createWriteStream, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { captureDesktopScreenshot, writeJsonArtifact } from './artifacts.js';
+import { cleanupDirectoryBestEffort, copyProjectToTemp } from './fs.js';
+import { readJsonFileWithRetry, terminateChildProcess, waitForChildExit, waitForFile } from './process.js';
+const DEFAULT_LAUNCH_TIMEOUT_MS = 120_000;
+const DEFAULT_PROCESS_EXIT_TIMEOUT_MS = 30_000;
+/**
+ * Runs a Volt app scenario in an isolated temp project copy.
+ * The launcher builds the copied project, launches the produced runtime artifact,
+ * waits for a JSON result file, validates the payload, and enforces process cleanup.
+ */
+export class VoltAppLauncher {
+    repoRoot;
+    cliEntryPath;
+    logger;
+    constructor(options) {
+        this.repoRoot = resolve(options.repoRoot);
+        this.cliEntryPath = resolve(options.cliEntryPath);
+        this.logger = options.logger;
+    }
+    /**
+     * Execute one scenario and return its validated payload.
+     * Set `preserveTempDir` when debugging to inspect generated temp artifacts.
+     */
+    async run(options) {
+        this.ensureCliEntry();
+        const sourceProjectDir = resolve(this.repoRoot, options.sourceProjectDir);
+        const timeoutMs = options.timeoutMs ?? DEFAULT_LAUNCH_TIMEOUT_MS;
+        const captureScreenshotOnError = options.captureScreenshotOnError ?? true;
+        const copied = copyProjectToTemp(sourceProjectDir, this.repoRoot);
+        const resultPath = join(copied.tempProjectDir, options.resultFile);
+        const artifactsDir = options.artifactsDir ? resolve(options.artifactsDir) : null;
+        const processLogPath = artifactsDir ? join(artifactsDir, options.logFileName ?? 'app-process.log') : null;
+        const screenshotPath = artifactsDir ? join(artifactsDir, options.screenshotFileName ?? 'failure.png') : null;
+        let logStream = null;
+        let child = null;
+        if (artifactsDir) {
+            mkdirSync(artifactsDir, { recursive: true });
+            if (processLogPath) {
+                logStream = createWriteStream(processLogPath, { flags: 'a' });
+            }
+        }
+        try {
+            if (options.prepareProject) {
+                await options.prepareProject(copied.tempProjectDir);
+            }
+            this.logger.log(`[volt:test] building ${options.sourceProjectDir}`);
+            this.buildProject(copied.tempProjectDir);
+            const runtimeBinaryPath = resolveRuntimeBinary(copied.tempProjectDir);
+            this.logger.log(`[volt:test] launching ${runtimeBinaryPath}`);
+            child = this.launchBinary(runtimeBinaryPath, copied.tempProjectDir);
+            attachChildOutput(child, logStream);
+            const resultReady = await waitForFile(resultPath, timeoutMs);
+            if (!resultReady) {
+                if (child) {
+                    await terminateChildProcess(child, `timeout waiting for ${options.resultFile}`, this.logger);
+                }
+                throw new Error(`[volt:test] timed out waiting for result file "${options.resultFile}" from ${options.sourceProjectDir}`);
+            }
+            const payload = await readJsonFileWithRetry(resultPath, 2_000);
+            const validatedPayload = options.validatePayload
+                ? options.validatePayload(payload)
+                : payload;
+            if (artifactsDir) {
+                writeJsonArtifact(join(artifactsDir, 'result-payload.json'), payload);
+            }
+            if (child) {
+                const exitResult = await waitForChildExit(child, DEFAULT_PROCESS_EXIT_TIMEOUT_MS);
+                if (!exitResult) {
+                    await terminateChildProcess(child, 'app did not exit after result write', this.logger);
+                    throw new Error(`[volt:test] app for ${options.sourceProjectDir} did not exit after reporting completion`);
+                }
+                if (exitResult.code !== 0) {
+                    throw new Error(`[volt:test] app for ${options.sourceProjectDir} exited with code ${exitResult.code} (signal: ${exitResult.signal ?? 'none'})`);
+                }
+            }
+            return validatedPayload;
+        }
+        catch (error) {
+            if (captureScreenshotOnError && screenshotPath) {
+                await captureDesktopScreenshot(screenshotPath, this.logger);
+            }
+            throw error;
+        }
+        finally {
+            if (child && (child.exitCode === null && child.signalCode === null)) {
+                await terminateChildProcess(child, 'suite cleanup', this.logger);
+            }
+            if (logStream) {
+                await closeWriteStream(logStream);
+            }
+            if (!options.preserveTempDir) {
+                await cleanupDirectoryBestEffort(copied.tempRoot, this.logger);
+            }
+            else {
+                this.logger.log(`[volt:test] preserved temp directory: ${copied.tempRoot}`);
+            }
+        }
+    }
+    ensureCliEntry() {
+        if (!existsSync(this.cliEntryPath)) {
+            throw new Error(`[volt:test] volt CLI entry not found: ${this.cliEntryPath}. Build @voltkit/volt-cli first.`);
+        }
+    }
+    buildProject(projectDir) {
+        execFileSync('node', [this.cliEntryPath, 'build'], {
+            cwd: projectDir,
+            stdio: 'inherit',
+            env: process.env,
+        });
+    }
+    launchBinary(binaryPath, cwd) {
+        if (process.platform === 'linux') {
+            return spawn('xvfb-run', ['-a', binaryPath], {
+                cwd,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                env: process.env,
+            });
+        }
+        return spawn(binaryPath, [], {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: process.env,
+        });
+    }
+}
+function resolveRuntimeBinary(projectDir) {
+    const manifestPath = join(projectDir, 'dist-volt', '.volt-runtime-artifact.json');
+    if (!existsSync(manifestPath)) {
+        throw new Error(`[volt:test] runtime manifest missing: ${manifestPath}`);
+    }
+    const manifestRaw = readFileSync(manifestPath, 'utf8');
+    const manifest = JSON.parse(manifestRaw);
+    if (!manifest || typeof manifest.artifactFileName !== 'string' || manifest.artifactFileName.length === 0) {
+        throw new Error(`[volt:test] invalid runtime manifest at ${manifestPath}`);
+    }
+    const binaryPath = join(projectDir, 'dist-volt', manifest.artifactFileName);
+    if (!existsSync(binaryPath)) {
+        throw new Error(`[volt:test] runtime binary missing: ${binaryPath}`);
+    }
+    return binaryPath;
+}
+function attachChildOutput(child, logStream) {
+    if (child.stdout) {
+        child.stdout.on('data', (chunk) => {
+            process.stdout.write(chunk);
+            if (logStream) {
+                logStream.write(chunk);
+            }
+        });
+    }
+    if (child.stderr) {
+        child.stderr.on('data', (chunk) => {
+            process.stderr.write(chunk);
+            if (logStream) {
+                logStream.write(chunk);
+            }
+        });
+    }
+}
+async function closeWriteStream(stream) {
+    await new Promise((resolveStream, reject) => {
+        stream.end(() => resolveStream());
+        stream.once('error', (error) => reject(error));
+    });
+}
+export const __testOnly = {
+    resolveRuntimeBinary,
+};
+//# sourceMappingURL=launcher.js.map

package/dist/launcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launcher.js","sourceRoot":"","sources":["../src/launcher.ts"],"names":[],"mappings":"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"}

package/dist/path.d.ts

@@ -0,0 +1 @@
+export declare function sanitizePathSegment(value: string): string;

package/dist/path.js

@@ -0,0 +1,11 @@
+export function sanitizePathSegment(value) {
+    const normalized = value
+        .trim()
+        .replace(/[\\/:*?"<>|]/g, '-')
+        .replace(/\s+/g, '-')
+        .replace(/[^a-zA-Z0-9._-]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    return normalized.length > 0 ? normalized : 'suite';
+}
+//# sourceMappingURL=path.js.map

package/dist/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,MAAM,UAAU,GAAG,KAAK;SACrB,IAAI,EAAE;SACN,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC;SAC7B,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC;SAChC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACzB,OAAO,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC;AACtD,CAAC"}

package/dist/process.d.ts

@@ -0,0 +1,10 @@
+import type { ChildProcess } from 'node:child_process';
+import type { VoltTestLogger } from './types.js';
+export interface ChildExitResult {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+}
+export declare function waitForFile(filePath: string, timeoutMs: number): Promise<boolean>;
+export declare function waitForChildExit(child: ChildProcess, timeoutMs: number): Promise<ChildExitResult | null>;
+export declare function terminateChildProcess(child: ChildProcess, reason: string, logger: VoltTestLogger): Promise<void>;
+export declare function readJsonFileWithRetry<T>(filePath: string, timeoutMs: number): Promise<T>;

package/dist/process.js

@@ -0,0 +1,71 @@
+import { readFileSync } from 'node:fs';
+import { setTimeout as delay } from 'node:timers/promises';
+export async function waitForFile(filePath, timeoutMs) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt <= timeoutMs) {
+        try {
+            readFileSync(filePath, 'utf8');
+            return true;
+        }
+        catch {
+            await delay(250);
+        }
+    }
+    return false;
+}
+export async function waitForChildExit(child, timeoutMs) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        return {
+            code: child.exitCode,
+            signal: child.signalCode,
+        };
+    }
+    const exitPromise = new Promise((resolve) => {
+        child.once('exit', (code, signal) => {
+            resolve({ code, signal });
+        });
+    });
+    const timeoutPromise = delay(timeoutMs).then(() => null);
+    return Promise.race([exitPromise, timeoutPromise]);
+}
+export async function terminateChildProcess(child, reason, logger) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        return;
+    }
+    try {
+        child.kill('SIGTERM');
+    }
+    catch (error) {
+        logger.warn(`[volt:test] failed to send SIGTERM (${reason}): ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const gracefulExit = await waitForChildExit(child, 5_000);
+    if (gracefulExit) {
+        return;
+    }
+    try {
+        child.kill('SIGKILL');
+    }
+    catch (error) {
+        throw new Error(`[volt:test] failed to send SIGKILL (${reason}): ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    const forcedExit = await waitForChildExit(child, 5_000);
+    if (!forcedExit) {
+        throw new Error(`[volt:test] child process did not exit after SIGKILL (${reason})`);
+    }
+}
+export async function readJsonFileWithRetry(filePath, timeoutMs) {
+    const startedAt = Date.now();
+    let lastError;
+    while (Date.now() - startedAt <= timeoutMs) {
+        try {
+            const content = readFileSync(filePath, 'utf8');
+            return JSON.parse(content);
+        }
+        catch (error) {
+            lastError = error;
+            await delay(100);
+        }
+    }
+    throw new Error(`[volt:test] failed to parse JSON at ${filePath} within ${timeoutMs}ms: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+}
+//# sourceMappingURL=process.js.map

package/dist/process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.js","sourceRoot":"","sources":["../src/process.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAQ3D,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,QAAgB,EAAE,SAAiB;IACnE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,IAAI,SAAS,EAAE,CAAC;QAC3C,IAAI,CAAC;YACH,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC/B,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,KAAmB,EACnB,SAAiB;IAEjB,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;QACzD,OAAO;YACL,IAAI,EAAE,KAAK,CAAC,QAAQ;YACpB,MAAM,EAAE,KAAK,CAAC,UAAU;SACzB,CAAC;IACJ,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,OAAO,CAAkB,CAAC,OAAO,EAAE,EAAE;QAC3D,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;YAClC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,MAAM,cAAc,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAEzD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,KAAmB,EACnB,MAAc,EACd,MAAsB;IAEtB,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;QACzD,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACxB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CACT,uCAAuC,MAAM,MAC3C,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CACvD,EAAE,CACH,CAAC;IACJ,CAAC;IAED,MAAM,YAAY,GAAG,MAAM,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC1D,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACxB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,uCAAuC,MAAM,MAC3C,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CACvD,EAAE,EACF,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACxD,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,yDAAyD,MAAM,GAAG,CAAC,CAAC;IACtF,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAI,QAAgB,EAAE,SAAiB;IAChF,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,IAAI,SAAkB,CAAC;IACvB,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,IAAI,SAAS,EAAE,CAAC;QAC3C,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC/C,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAM,CAAC;QAClC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,SAAS,GAAG,KAAK,CAAC;YAClB,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CACb,uCAAuC,QAAQ,WAAW,SAAS,OACjE,SAAS,YAAY,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CACnE,EAAE,CACH,CAAC;AACJ,CAAC"}

package/dist/runner.d.ts

@@ -0,0 +1,11 @@
+import type { RunSuitesOptions, VoltTestConfig, VoltTestLogger, VoltTestSuite } from './types.js';
+export declare function runSuites(config: VoltTestConfig, options: RunSuitesOptions): Promise<void>;
+declare function selectSuites(suites: readonly VoltTestSuite[], names?: readonly string[]): VoltTestSuite[];
+declare function withTimeout(promise: Promise<void>, timeoutMs: number, suiteName: string): Promise<void>;
+declare function withPrefix(logger: VoltTestLogger, prefix: string): VoltTestLogger;
+export declare const __testOnly: {
+    selectSuites: typeof selectSuites;
+    withTimeout: typeof withTimeout;
+    withPrefix: typeof withPrefix;
+};
+export {};

package/dist/runner.js

@@ -0,0 +1,230 @@
+import { join, resolve } from 'node:path';
+import { captureDesktopScreenshot, createRunArtifactRoot, createSuiteAttemptArtifactDir, writeJsonArtifact, } from './artifacts.js';
+import { validateTestConfig } from './config.js';
+import { sanitizePathSegment } from './path.js';
+const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_RETRIES = 0;
+export async function runSuites(config, options) {
+    validateTestConfig(config, 'test config');
+    const logger = options.logger ?? toLogger(console);
+    const selectedSuites = selectSuites(config.suites, options.suiteNames);
+    const defaultTimeoutMs = options.timeoutMs ?? config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const retries = options.retries ?? config.retries ?? DEFAULT_RETRIES;
+    const captureScreenshots = options.captureScreenshots ?? true;
+    const repoRoot = resolve(options.repoRoot ?? process.cwd());
+    const cliEntryPath = resolve(options.cliEntryPath);
+    const runArtifactRoot = createRunArtifactRoot(repoRoot, options.artifactDir ?? config.artifactDir);
+    validateRetryCount(retries);
+    logger.log(`[volt:test] running ${selectedSuites.length} suite(s)`);
+    logger.log(`[volt:test] retries per suite: ${retries}`);
+    logger.log(`[volt:test] artifact root: ${runArtifactRoot}`);
+    const startedAt = Date.now();
+    const suiteSummaries = [];
+    let completed = 0;
+    let firstFailure = null;
+    for (const suite of selectedSuites) {
+        const suiteTimeoutMs = suite.timeoutMs ?? defaultTimeoutMs;
+        const suiteStartedAt = Date.now();
+        const suiteResult = await runSuiteWithRetries({
+            suite,
+            retries,
+            suiteTimeoutMs,
+            repoRoot,
+            cliEntryPath,
+            runArtifactRoot,
+            captureScreenshots,
+            logger,
+        });
+        const suiteSummary = suiteResult.summary;
+        suiteSummaries.push(suiteSummary);
+        completed += 1;
+        if (suiteSummary.passed) {
+            logger.log(`[volt:test] [${suite.name}] passed in ${suiteSummary.durationMs}ms`);
+        }
+        else {
+            logger.error(`[volt:test] [${suite.name}] failed in ${suiteSummary.durationMs}ms`);
+        }
+        if (suiteSummary.passed && suiteSummary.flaky) {
+            logger.warn(`[volt:test] [${suite.name}] marked flaky: passed after retry.`);
+        }
+        writeJsonArtifact(join(runArtifactRoot, sanitizePathSegment(suite.name), 'suite-summary.json'), {
+            ...suiteSummary,
+            finishedAt: new Date().toISOString(),
+            suiteTimeoutMs,
+            suiteDurationMs: Date.now() - suiteStartedAt,
+        });
+        if (suiteResult.error && !firstFailure) {
+            firstFailure = suiteResult.error;
+            break;
+        }
+    }
+    const finishedAt = Date.now();
+    const runSummary = {
+        startedAt: new Date(startedAt).toISOString(),
+        finishedAt: new Date(finishedAt).toISOString(),
+        durationMs: finishedAt - startedAt,
+        suites: suiteSummaries,
+    };
+    writeJsonArtifact(join(runArtifactRoot, 'run-summary.json'), runSummary);
+    const flakySuites = suiteSummaries.filter((suite) => suite.flaky).map((suite) => suite.name);
+    if (flakySuites.length > 0) {
+        writeJsonArtifact(join(runArtifactRoot, 'flake-report.json'), {
+            flakySuites,
+            count: flakySuites.length,
+            generatedAt: new Date().toISOString(),
+        });
+    }
+    logger.log(`[volt:test] completed ${completed}/${selectedSuites.length} suite(s) in ${finishedAt - startedAt}ms`);
+    if (firstFailure) {
+        throw firstFailure;
+    }
+}
+async function runSuiteWithRetries(args) {
+    const { suite, retries, suiteTimeoutMs, repoRoot, cliEntryPath, runArtifactRoot, captureScreenshots, logger } = args;
+    const attempts = [];
+    const maxAttempts = retries + 1;
+    const suiteStart = Date.now();
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        const attemptStart = Date.now();
+        const attemptArtifactDir = createSuiteAttemptArtifactDir(runArtifactRoot, suite.name, attempt);
+        const prefixedLogger = withPrefix(logger, `[volt:test] [${suite.name}] [attempt ${attempt}/${maxAttempts}]`);
+        prefixedLogger.log('start');
+        prefixedLogger.log(`artifacts: ${attemptArtifactDir}`);
+        const captureScreenshot = async (name = 'screenshot') => {
+            const screenshotPath = join(attemptArtifactDir, `${sanitizePathSegment(name)}.png`);
+            if (!captureScreenshots) {
+                return { path: screenshotPath, captured: false };
+            }
+            const captured = await captureDesktopScreenshot(screenshotPath, prefixedLogger);
+            return { path: screenshotPath, captured };
+        };
+        try {
+            await withTimeout(suite.run({
+                repoRoot,
+                cliEntryPath,
+                logger: prefixedLogger,
+                timeoutMs: suiteTimeoutMs,
+                suiteName: suite.name,
+                attempt,
+                artifactsDir: attemptArtifactDir,
+                captureScreenshot,
+            }), suiteTimeoutMs, suite.name);
+            attempts.push({
+                attempt,
+                durationMs: Date.now() - attemptStart,
+                status: 'passed',
+            });
+            return {
+                summary: {
+                    name: suite.name,
+                    attempts,
+                    flaky: attempt > 1,
+                    durationMs: Date.now() - suiteStart,
+                    passed: true,
+                },
+                error: null,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            let screenshotPath;
+            if (captureScreenshots) {
+                const screenshot = await captureScreenshot(`failure-${attempt}`);
+                if (screenshot.captured) {
+                    screenshotPath = screenshot.path;
+                }
+            }
+            attempts.push({
+                attempt,
+                durationMs: Date.now() - attemptStart,
+                status: 'failed',
+                error: message,
+                screenshotPath,
+            });
+            prefixedLogger.error(message);
+            if (attempt < maxAttempts) {
+                prefixedLogger.warn('retrying after failure');
+                continue;
+            }
+            return {
+                summary: {
+                    name: suite.name,
+                    attempts,
+                    flaky: false,
+                    durationMs: Date.now() - suiteStart,
+                    passed: false,
+                },
+                error,
+            };
+        }
+    }
+    const internalError = new Error('[volt:test] internal runner error: no suite attempts executed.');
+    return {
+        summary: {
+            name: suite.name,
+            attempts: [],
+            flaky: false,
+            durationMs: 0,
+            passed: false,
+        },
+        error: internalError,
+    };
+}
+function selectSuites(suites, names) {
+    if (!names || names.length === 0) {
+        return [...suites];
+    }
+    const wanted = new Set(names);
+    const selected = suites.filter((suite) => wanted.has(suite.name));
+    if (selected.length === 0) {
+        throw new Error(`[volt:test] none of the requested suites were found: ${names.join(', ')}`);
+    }
+    const missing = names.filter((name) => !selected.some((suite) => suite.name === name));
+    if (missing.length > 0) {
+        throw new Error(`[volt:test] unknown suite(s): ${missing.join(', ')}`);
+    }
+    return selected;
+}
+async function withTimeout(promise, timeoutMs, suiteName) {
+    let timeoutHandle = null;
+    try {
+        await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timeoutHandle = setTimeout(() => {
+                    reject(new Error(`[volt:test] suite "${suiteName}" timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+        }
+    }
+}
+function withPrefix(logger, prefix) {
+    return {
+        log: (message) => logger.log(`${prefix} ${message}`),
+        warn: (message) => logger.warn(`${prefix} ${message}`),
+        error: (message) => logger.error(`${prefix} ${message}`),
+    };
+}
+function validateRetryCount(retries) {
+    if (!Number.isInteger(retries) || retries < 0) {
+        throw new Error('[volt:test] retries must be a non-negative integer.');
+    }
+}
+function toLogger(source) {
+    return {
+        log: (message) => source.log(message),
+        warn: (message) => source.warn(message),
+        error: (message) => source.error(message),
+    };
+}
+export const __testOnly = {
+    selectSuites,
+    withTimeout,
+    withPrefix,
+};
+//# sourceMappingURL=runner.js.map