@testspectra/cli 1.0.0

package/dist/config/schema.d.ts

@@ -0,0 +1,365 @@
+/**
+ * Configuration for web automation and browser test runners.
+ */
+export interface WebConfig {
+    /**
+     * Base URL used to resolve relative paths in tests (e.g. `browser.url('/login')` or `browser.intercept('/api/users')`).
+     * @default "http://localhost:3000"
+     */
+    baseUrl: string;
+    /**
+     * Maximum number of parallel browser sessions/workers spawned during test execution.
+     * @default "1"
+     */
+    maxConcurrentSessions: string;
+    /**
+     * Whether to run browsers in headless mode without a visible GUI window.
+     * @default true
+     */
+    headlessMode: boolean;
+    /**
+     * Implicit wait timeout (in milliseconds) for finding elements before throwing an error.
+     * @default "5000"
+     */
+    implicitWait: string;
+    /**
+     * Maximum time (in milliseconds) allowed for a webpage to complete navigation and initial load.
+     * @default "30000"
+     */
+    pageLoadTimeout: string;
+    /**
+     * Maximum time (in milliseconds) allowed for asynchronous scripts to finish executing.
+     * @default "30000"
+     */
+    scriptTimeout: string;
+    /**
+     * Parallelization granularity:
+     * - `"testcase"`: Each test case executes in parallel across available workers.
+     * - `"suite"`: Test cases within a suite run serially, while different suites run in parallel.
+     * @default "testcase"
+     */
+    parallelizationMode: "testcase" | "suite";
+}
+/**
+ * Browser target definition for web test execution.
+ */
+export interface Browser {
+    /**
+     * Unique identifier for this browser configuration.
+     */
+    id: string;
+    /**
+     * Browser type/engine: `"chrome"`, `"firefox"`, `"safari"`, `"edge"`.
+     * @default "chrome"
+     */
+    type: string;
+    /**
+     * Whether to simulate mobile viewport and touch metrics.
+     * @default false
+     */
+    mobileEmulation: boolean;
+    /**
+     * Emulated device name when `mobileEmulation` is true (e.g. `"iPhone 14"`, `"Pixel 7"`).
+     */
+    deviceName?: string;
+    /**
+     * Custom browser window width in pixels.
+     */
+    width?: string;
+    /**
+     * Custom browser window height in pixels.
+     */
+    height?: string;
+}
+/**
+ * Configuration for Android mobile test automation with Appium & UiAutomator2.
+ */
+export interface AndroidConfig {
+    /**
+     * Appium server endpoint URL.
+     * @default "http://127.0.0.1:4723"
+     */
+    appiumServer: string;
+    /**
+     * Mobile platform name.
+     * @default "Android"
+     */
+    platformName: string;
+    /**
+     * Android OS version (e.g. `"13"`, `"14"`).
+     * @default "13"
+     */
+    platformVersion: string;
+    /**
+     * Target Android device name or ADB serial ID (e.g. `"emulator-5554"`).
+     * @default "emulator-5554"
+     */
+    deviceName: string;
+    /**
+     * Appium mobile automation driver engine.
+     * @default "UiAutomator2"
+     */
+    automationName: string;
+    /**
+     * Android application package name (e.g. `"com.example.app"`).
+     */
+    appPackage: string;
+    /**
+     * Main activity name launched when starting the app.
+     */
+    appActivity: string;
+    /**
+     * Whether to automatically grant Android runtime permissions upon installation.
+     * @default true
+     */
+    autoGrantPermissions: boolean;
+    /**
+     * Whether to preserve app state and prevent clearing app data/cache between sessions.
+     * @default false
+     */
+    noReset: boolean;
+    /**
+     * Implicit wait timeout (in milliseconds) for locating mobile elements.
+     * @default "10000"
+     */
+    implicitWait: string;
+    /**
+     * Parallelization execution mode for Android mobile tests.
+     * @default "suite"
+     */
+    parallelizationMode: "testcase" | "suite";
+}
+/**
+ * Configuration for iOS mobile test automation with Appium & XCUITest.
+ */
+export interface IosConfig {
+    /**
+     * Appium server endpoint URL.
+     * @default "http://127.0.0.1:4723"
+     */
+    appiumServer: string;
+    /**
+     * Mobile platform name.
+     * @default "iOS"
+     */
+    platformName: string;
+    /**
+     * iOS version (e.g. `"16.0"`, `"17.0"`).
+     * @default "16.0"
+     */
+    platformVersion: string;
+    /**
+     * iOS simulator or connected physical device name (e.g. `"iPhone 14"`).
+     * @default "iPhone 14"
+     */
+    deviceName: string;
+    /**
+     * Appium mobile automation driver engine for iOS.
+     * @default "XCUITest"
+     */
+    automationName: string;
+    /**
+     * iOS Application Bundle Identifier (e.g. `"com.example.iosapp"`).
+     */
+    bundleId: string;
+    /**
+     * Target device Unique Device Identifier (UDID) or `"auto"`.
+     * @default "auto"
+     */
+    udid: string;
+    /**
+     * Apple Developer Team 10-character Organization ID for code signing.
+     */
+    xcodeOrgId: string;
+    /**
+     * Xcode code signing identity string (e.g. `"iPhone Developer"`).
+     * @default "iPhone Developer"
+     */
+    xcodeSigningId: string;
+    /**
+     * Whether to automatically accept iOS system permission alerts.
+     * @default true
+     */
+    autoAcceptAlerts: boolean;
+    /**
+     * Whether to preserve app state between sessions.
+     * @default false
+     */
+    noReset: boolean;
+    /**
+     * Implicit wait timeout (in milliseconds) for locating iOS UI elements.
+     * @default "10000"
+     */
+    implicitWait: string;
+    /**
+     * Parallelization execution mode for iOS mobile tests.
+     * @default "suite"
+     */
+    parallelizationMode: "testcase" | "suite";
+}
+/**
+ * Load testing stage ramp-up profile.
+ */
+export interface LoadStage {
+    /**
+     * Stage identifier.
+     */
+    id: string;
+    /**
+     * Duration for this load stage (e.g. `"30s"`, `"2m"`).
+     */
+    duration: string;
+    /**
+     * Target virtual users (VUs) to scale to during this stage.
+     */
+    targetVUs: string;
+}
+/**
+ * Performance and pass/fail metric threshold definition.
+ */
+export interface SuccessThreshold {
+    /**
+     * Unique threshold identifier.
+     */
+    id: string;
+    /**
+     * Performance metric type (e.g. `"http_req_duration"`, `"http_req_failed"`).
+     */
+    metricType: string;
+    /**
+     * Maximum acceptable value (e.g. `"500ms"`, `"0.01"`).
+     */
+    maxValue: string;
+}
+/**
+ * Specific domain filter for real-time network interception and recording.
+ */
+export interface MonitoredDomain {
+    /**
+     * Hostname or regex pattern to monitor (e.g. `"api.example.com"`).
+     */
+    domain: string;
+    /**
+     * Whether network logging and CDP interception is active for this domain.
+     */
+    enabled: boolean;
+}
+/**
+ * Custom environment variable key-value pair injected into the test execution sandbox.
+ */
+export interface EnvironmentVariable {
+    /**
+     * Environment variable name (e.g. `"API_SECRET_KEY"`).
+     */
+    key: string;
+    /**
+     * Environment variable value.
+     */
+    value: string;
+}
+/**
+ * Test execution, CDP network monitoring, and sandbox environment configuration.
+ */
+export interface ExecutionConfig {
+    /**
+     * Whether to record network requests and timing metrics via Chrome DevTools Protocol.
+     * @default true
+     */
+    networkMonitoringEnabled: boolean;
+    /**
+     * Upper threshold (in milliseconds) classified as a fast network response.
+     * @default "200"
+     */
+    fastResponseTime: string;
+    /**
+     * Upper threshold (in milliseconds) classified as a normal network response.
+     * @default "1000"
+     */
+    normalResponseTime: string;
+    /**
+     * Whitelist of domains to monitor. If empty, all requests are captured.
+     */
+    monitoredDomains?: MonitoredDomain[];
+    /**
+     * Custom environment variables injected into the test process runtime.
+     */
+    environmentVariables?: EnvironmentVariable[];
+}
+/**
+ * Root configuration data structure matching TestSpectra project schema.
+ */
+export interface ConfigData {
+    /**
+     * Web browser execution settings.
+     */
+    webConfig: WebConfig;
+    /**
+     * List of target browsers for web automation runs.
+     */
+    browsers: Browser[];
+    /**
+     * Android Appium driver and device options.
+     */
+    androidConfig: AndroidConfig;
+    /**
+     * iOS Appium driver and device options.
+     */
+    iosConfig: IosConfig;
+    /**
+     * Load testing parameters.
+     */
+    loadConfig: {
+        virtualUsers: string;
+        duration: string;
+    };
+    /**
+     * Load testing stages.
+     */
+    loadStages: LoadStage[];
+    /**
+     * Pass/fail metric thresholds.
+     */
+    thresholds: SuccessThreshold[];
+    /**
+     * Advanced execution and network recording settings.
+     */
+    executionConfig?: ExecutionConfig;
+}
+/**
+ * Deep recursive partial type for user-friendly configuration objects.
+ */
+export type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * User-provided configuration options with optional deep partial properties.
+ */
+export type UserConfig = DeepPartial<ConfigData>;
+/**
+ * Helper function providing type hinting and autocompletion for `spectra.config.ts`.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from "@testspectra/cli";
+ *
+ * export default defineConfig({
+ *   webConfig: {
+ *     baseUrl: "https://example.com",
+ *     headlessMode: false,
+ *   },
+ * });
+ * ```
+ */
+export declare function defineConfig(config: UserConfig): UserConfig;
+/**
+ * Complete project persistence record.
+ */
+export interface ProjectConfig {
+    project_id: string;
+    config_data: ConfigData;
+    updated_at?: string;
+}
+/**
+ * Default fallback configuration object.
+ */
+export declare const DEFAULT_CONFIG_DATA: ConfigData;

package/dist/config/schema.js

@@ -0,0 +1,80 @@
+/**
+ * Helper function providing type hinting and autocompletion for `spectra.config.ts`.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from "@testspectra/cli";
+ *
+ * export default defineConfig({
+ *   webConfig: {
+ *     baseUrl: "https://example.com",
+ *     headlessMode: false,
+ *   },
+ * });
+ * ```
+ */
+export function defineConfig(config) {
+    return config;
+}
+/**
+ * Default fallback configuration object.
+ */
+export const DEFAULT_CONFIG_DATA = {
+    webConfig: {
+        baseUrl: "http://localhost:3000",
+        maxConcurrentSessions: "1",
+        headlessMode: true,
+        implicitWait: "5000",
+        pageLoadTimeout: "30000",
+        scriptTimeout: "30000",
+        parallelizationMode: "testcase",
+    },
+    browsers: [
+        {
+            id: "chrome-desktop",
+            type: "chrome",
+            mobileEmulation: false,
+        },
+    ],
+    androidConfig: {
+        appiumServer: "http://127.0.0.1:4723",
+        platformName: "Android",
+        platformVersion: "13",
+        deviceName: "emulator-5554",
+        automationName: "UiAutomator2",
+        appPackage: "",
+        appActivity: "",
+        autoGrantPermissions: true,
+        noReset: false,
+        implicitWait: "10000",
+        parallelizationMode: "suite",
+    },
+    iosConfig: {
+        appiumServer: "http://127.0.0.1:4723",
+        platformName: "iOS",
+        platformVersion: "16.0",
+        deviceName: "iPhone 14",
+        automationName: "XCUITest",
+        bundleId: "",
+        udid: "auto",
+        xcodeOrgId: "",
+        xcodeSigningId: "iPhone Developer",
+        autoAcceptAlerts: true,
+        noReset: false,
+        implicitWait: "10000",
+        parallelizationMode: "suite",
+    },
+    loadConfig: {
+        virtualUsers: "10",
+        duration: "1m",
+    },
+    loadStages: [],
+    thresholds: [],
+    executionConfig: {
+        networkMonitoringEnabled: true,
+        fastResponseTime: "200",
+        normalResponseTime: "1000",
+        monitoredDomains: [],
+        environmentVariables: [],
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "commander";
+export * from "./config/schema.js";
+export * from "./config/loader.js";
+export * from "./types/generator.js";
+export declare function createCliProgram(): Command;
+export declare function runCli(args?: string[]): Promise<void>;

package/dist/index.js

@@ -0,0 +1,51 @@
+import { Command } from "commander";
+import { devicesCommand } from "./commands/devices.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { initCommand } from "./commands/init.js";
+import { runCommand } from "./commands/run.js";
+import { watchCommand } from "./commands/watch.js";
+export * from "./config/schema.js";
+export * from "./config/loader.js";
+export * from "./types/generator.js";
+export function createCliProgram() {
+    const program = new Command();
+    program
+        .name("spectra")
+        .description("TestSpectra Zero-Config Cross-Platform Test Runner CLI")
+        .version("2.0.0");
+    program
+        .command("init")
+        .description("Initialize testspectra.config.json and project directories")
+        .option("-f, --force", "Overwrite existing configuration if present")
+        .action(initCommand);
+    program
+        .command("doctor")
+        .description("Verify local environment prerequisites (ADB, Java, Chrome, Bun, Node)")
+        .option("--fix", "Attempt automatic fix / download of missing tools")
+        .action(doctorCommand);
+    program
+        .command("devices")
+        .description("List connected Android/iOS devices and local browsers")
+        .option("-t, --target <target>", "Filter scope: android, ios, web, all", "all")
+        .action(devicesCommand);
+    program
+        .command("run [path]")
+        .description("Execute test suite or individual test case")
+        .option("-t, --target <target>", "Target platform: web, android, ios, common", "web")
+        .option("-d, --device <device>", "Target device name or UDID")
+        .option("--headless", "Run in headless mode")
+        .option("--no-headless", "Run in headed mode")
+        .option("-w, --workdir <dir>", "Custom app data / temp workdir")
+        .option("-o, --output <path>", "Custom test report JSON output path")
+        .action(runCommand);
+    program
+        .command("watch")
+        .description("Watch page-objects, actions, steps, fixtures and auto-regenerate ambient types")
+        .option("--once", "Generate ambient types once and exit")
+        .action(watchCommand);
+    return program;
+}
+export async function runCli(args = process.argv) {
+    const program = createCliProgram();
+    await program.parseAsync(args);
+}

package/dist/runner/bridge.d.ts

@@ -0,0 +1,20 @@
+import { ConfigData } from "../config/schema.js";
+import { Reporter, TestRunResult } from "./reporter.js";
+export interface RunOptions {
+    baseDir: string;
+    appDataPath: string;
+    platform: "web" | "android" | "ios" | "common";
+    suite: string;
+    testCases: Array<{
+        id: string;
+        title: string;
+        executionOrder?: number;
+    }>;
+    config: ConfigData;
+    targetDevice?: string;
+    outputJsonPath?: string;
+}
+export declare class RustCoreBridge {
+    static resolveBinaryPath(): string;
+    static run(options: RunOptions, reporter: Reporter): Promise<TestRunResult>;
+}

package/dist/runner/bridge.js

@@ -0,0 +1,122 @@
+import { spawn } from "child_process";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export class RustCoreBridge {
+    static resolveBinaryPath() {
+        // 1. Look for precompiled release/debug binary in workspace target
+        const workspaceRoot = path.resolve(__dirname, "../../..");
+        const candidatePaths = [
+            path.join(workspaceRoot, "target/debug/testspectra-runner"),
+            path.join(workspaceRoot, "target/release/testspectra-runner"),
+            path.join(workspaceRoot, "core/test-runner/target/debug/testspectra-runner"),
+            path.join(workspaceRoot, "core/test-runner/target/release/testspectra-runner"),
+            path.join(__dirname, "../../bin/testspectra-runner"),
+        ];
+        for (const p of candidatePaths) {
+            if (fs.existsSync(p)) {
+                return p;
+            }
+            if (fs.existsSync(`${p}.exe`)) {
+                return `${p}.exe`;
+            }
+        }
+        return "cargo"; // Fallback to cargo run
+    }
+    static async run(options, reporter) {
+        const binPath = this.resolveBinaryPath();
+        const payload = JSON.stringify({
+            baseDir: options.baseDir,
+            appDataPath: options.appDataPath,
+            platform: options.platform,
+            suite: options.suite,
+            testCases: options.testCases,
+            config: options.config,
+            targetDevice: options.targetDevice,
+        });
+        return new Promise((resolve, reject) => {
+            let child;
+            if (binPath === "cargo") {
+                const workspaceRoot = path.resolve(__dirname, "../../..");
+                child = spawn("cargo", ["run", "--manifest-path", "core/test-runner/Cargo.toml", "--bin", "testspectra-runner", "--", payload], {
+                    cwd: workspaceRoot,
+                    env: { ...process.env, RUST_LOG: "info" },
+                });
+            }
+            else {
+                child = spawn(binPath, [payload], {
+                    env: { ...process.env, RUST_LOG: "info" },
+                });
+            }
+            let runStatus = "failed";
+            let runDuration = "0s";
+            child.stdout.on("data", (data) => {
+                const lines = data.toString().split("\n");
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const parsed = JSON.parse(line);
+                        if (parsed.type === "log") {
+                            reporter.addLog({
+                                timestamp: parsed.timestamp,
+                                level: parsed.level,
+                                message: parsed.message,
+                            });
+                        }
+                        else if (parsed.type === "network") {
+                            reporter.addNetwork({
+                                requestId: parsed.requestId,
+                                url: parsed.url,
+                                method: parsed.method,
+                                status: parsed.status,
+                            });
+                        }
+                        else if (parsed.type === "complete") {
+                            runStatus = parsed.status;
+                            runDuration = parsed.duration;
+                        }
+                        else if (parsed.type === "error") {
+                            reporter.addLog({
+                                timestamp: new Date().toLocaleTimeString(),
+                                level: "ERROR",
+                                message: parsed.message,
+                            });
+                        }
+                    }
+                    catch {
+                        // Raw non-JSON output (cargo compile warnings, etc.)
+                        console.log(line);
+                    }
+                }
+            });
+            child.stderr.on("data", (data) => {
+                const str = data.toString();
+                // Ignore normal compilation progress
+                if (!str.includes("Compiling") && !str.includes("Checking") && !str.includes("Finished")) {
+                    reporter.addLog({
+                        timestamp: new Date().toLocaleTimeString(),
+                        level: "DEBUG",
+                        message: str.trim(),
+                    });
+                }
+            });
+            child.on("close", (code) => {
+                const result = reporter.generateResult(code === 0 ? "passed" : runStatus, runDuration);
+                if (options.outputJsonPath) {
+                    const outDir = path.dirname(options.outputJsonPath);
+                    if (!fs.existsSync(outDir)) {
+                        fs.mkdirSync(outDir, { recursive: true });
+                    }
+                    fs.writeFileSync(options.outputJsonPath, JSON.stringify(result, null, 2), "utf-8");
+                }
+                resolve(result);
+            });
+            child.on("error", (err) => {
+                reject(err);
+            });
+        });
+    }
+}

package/dist/runner/reporter.d.ts

@@ -0,0 +1,26 @@
+export interface TestLog {
+    timestamp: string;
+    level: "INFO" | "SUCCESS" | "WARNING" | "ERROR" | "DEBUG" | string;
+    message: string;
+}
+export interface NetworkResource {
+    requestId: string;
+    url: string;
+    method: string;
+    status: number;
+}
+export interface TestRunResult {
+    status: "passed" | "failed" | "error" | string;
+    duration: string;
+    logs: TestLog[];
+    networkResources?: NetworkResource[];
+}
+export declare class Reporter {
+    private logs;
+    private networkEvents;
+    addLog(log: TestLog): void;
+    addNetwork(res: NetworkResource): void;
+    getLogs(): TestLog[];
+    getNetworkEvents(): NetworkResource[];
+    generateResult(status: string, duration: string): TestRunResult;
+}