@testspectra/cli 1.0.69 → 1.1.0

package/dist/commands/update.js

@@ -0,0 +1,109 @@
+import { execSync, execFileSync } 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);
+const PACKAGES = ['@testspectra/cli', '@testspectra/matchers'];
+function getLatestVersion(pkg) {
+    try {
+        const out = execFileSync('npm', ['view', pkg, 'version', '--json'], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 10000,
+        })
+            .toString()
+            .trim()
+            .replace(/"/g, '');
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+function getCurrentVersion(pkg, cwd) {
+    // Walk up to find the installed version
+    let cur = path.resolve(cwd);
+    while (cur && cur !== path.dirname(cur)) {
+        const pkgJson = path.join(cur, 'node_modules', pkg, 'package.json');
+        if (fs.existsSync(pkgJson)) {
+            try {
+                const p = JSON.parse(fs.readFileSync(pkgJson, 'utf-8'));
+                return p.version ?? null;
+            }
+            catch { }
+        }
+        cur = path.dirname(cur);
+    }
+    return null;
+}
+function detectPackageManager(cwd) {
+    if (fs.existsSync(path.join(cwd, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (fs.existsSync(path.join(cwd, 'bun.lockb')) || fs.existsSync(path.join(cwd, 'bun.lock')))
+        return 'bun';
+    return 'npm';
+}
+function buildInstallCmd(pm, pkgSpecs) {
+    const list = pkgSpecs.join(' ');
+    switch (pm) {
+        case 'pnpm':
+            return `pnpm add -D ${list}`;
+        case 'bun':
+            return `bun add -d ${list}`;
+        case 'npm':
+        default:
+            return `npm install -D ${list}`;
+    }
+}
+export async function updateCommand(options = {}) {
+    const cwd = process.cwd();
+    const pm = detectPackageManager(cwd);
+    console.log('\x1b[36m┌  🔄 TestSpectra Self-Update\x1b[0m');
+    console.log('\x1b[36m│\x1b[0m');
+    console.log(`\x1b[36m│\x1b[0m  Package Manager: \x1b[33m${pm}\x1b[0m`);
+    console.log('\x1b[36m│\x1b[0m');
+    console.log('\x1b[36m│\x1b[0m  Fetching latest versions from npm registry...');
+    const updates = [];
+    for (const pkg of PACKAGES) {
+        const current = getCurrentVersion(pkg, cwd);
+        const latest = getLatestVersion(pkg);
+        const needsUpdate = !!latest && latest !== current;
+        updates.push({ pkg, current, latest, needsUpdate });
+        const currentStr = current ? `\x1b[33mv${current}\x1b[0m` : '\x1b[90m(not installed)\x1b[0m';
+        const latestStr = latest ? `\x1b[32mv${latest}\x1b[0m` : '\x1b[31m(unavailable)\x1b[0m';
+        const arrow = needsUpdate ? ` → ${latestStr}` : '';
+        const status = !latest ? '\x1b[31m✗\x1b[0m' : needsUpdate ? '\x1b[33m↑\x1b[0m' : '\x1b[32m✓\x1b[0m';
+        console.log(`\x1b[36m│\x1b[0m   ${status} ${pkg.padEnd(28)} ${currentStr}${arrow}`);
+    }
+    const toUpdate = updates.filter((u) => u.needsUpdate && u.latest);
+    console.log('\x1b[36m│\x1b[0m');
+    if (toUpdate.length === 0) {
+        console.log('\x1b[36m└──────────────────────────────────────────────────────────\x1b[0m');
+        console.log('\x1b[32m✓ All TestSpectra packages are already up-to-date!\x1b[0m\n');
+        return;
+    }
+    if (options.check) {
+        console.log(`\x1b[36m│\x1b[0m  \x1b[33m${toUpdate.length} update(s) available. Run \x1b[36mspectra update\x1b[33m to install.\x1b[0m`);
+        console.log('\x1b[36m└──────────────────────────────────────────────────────────\x1b[0m\n');
+        return;
+    }
+    const pkgSpecs = toUpdate.map((u) => `${u.pkg}@${u.latest}`);
+    const installCmd = buildInstallCmd(pm, pkgSpecs);
+    console.log(`\x1b[36m│\x1b[0m  Running: \x1b[90m${installCmd}\x1b[0m`);
+    console.log('\x1b[36m│\x1b[0m');
+    try {
+        execSync(installCmd, { cwd, stdio: 'inherit' });
+        console.log('\x1b[36m│\x1b[0m');
+        console.log('\x1b[36m└──────────────────────────────────────────────────────────\x1b[0m');
+        console.log('\x1b[32m🎉 TestSpectra updated successfully!\x1b[0m');
+        for (const u of toUpdate) {
+            console.log(`   \x1b[32m✓\x1b[0m ${u.pkg}: v${u.current ?? '?'} → v${u.latest}`);
+        }
+        console.log('');
+    }
+    catch (err) {
+        console.log('\x1b[36m└──────────────────────────────────────────────────────────\x1b[0m');
+        console.error(`\x1b[31m✗ Update failed: ${err.message}\x1b[0m\n`);
+        process.exit(1);
+    }
+}

package/dist/commands/watch.d.ts

@@ -1,4 +1,10 @@
+import fs from 'fs';
 export interface WatchCommandOptions {
     cwd?: string;
+    debounceMs?: number;
 }
+export declare function startWatcher(cwd: string, debounceMs?: number): {
+    watcher: fs.FSWatcher;
+    close: () => void;
+};
 export declare function watchCommand(options?: WatchCommandOptions): Promise<void>;

package/dist/commands/watch.js

@@ -1,63 +1,67 @@
-import fs from "fs";
-import path from "path";
-import chalk from "chalk";
-import { TypeGenerator } from "../types/generator.js";
-export async function watchCommand(options = {}) {
-    const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
-    console.log(chalk.bold.cyan("\n🔭 TestSpectra Ambient Types Watcher"));
-    console.log(chalk.gray(`Watching workspace: ${cwd}\n`));
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { TypeGenerator } from '../types/generator.js';
+export function startWatcher(cwd, debounceMs = 60) {
     // Initial generation
-    try {
-        TypeGenerator.writeDeclarationFiles(cwd);
-        console.log(chalk.green("✔ Initialized ambient declarations in .testspectra/types/"));
-    }
-    catch (err) {
-        console.error(chalk.red(`✖ Failed initial type generation: ${err?.message}`));
-    }
+    TypeGenerator.generateAll(cwd);
     let debounceTimer = null;
     const triggerRegen = (filePath, eventType) => {
         if (debounceTimer)
             clearTimeout(debounceTimer);
         debounceTimer = setTimeout(() => {
             try {
-                TypeGenerator.writeDeclarationFiles(cwd);
+                TypeGenerator.generateAll(cwd);
                 const time = new Date().toLocaleTimeString();
                 const rel = path.relative(cwd, filePath) || filePath;
-                console.log(chalk.gray(`[${time}] `) +
-                    chalk.cyan(`✨ Updated ambient types `) +
-                    chalk.gray(`(${eventType}: ${rel})`));
+                console.log(chalk.gray(`[${time}] `) + chalk.cyan(`✨ Updated ambient types `) + chalk.gray(`(${eventType}: ${rel})`));
             }
             catch (err) {
                 console.error(chalk.red(`✖ Error regenerating declarations: ${err?.message}`));
             }
-        }, 100);
+        }, debounceMs);
+    };
+    const watcher = fs.watch(cwd, { recursive: true }, (eventType, filename) => {
+        if (!filename)
+            return;
+        const fn = filename.toString();
+        if (fn.includes('.testspectra') ||
+            fn.includes('node_modules') ||
+            fn.includes('.git') ||
+            fn.includes('dist') ||
+            fn.includes('.nx')) {
+            return;
+        }
+        if (fn.includes('fixtures') ||
+            fn.includes('page-objects') ||
+            fn.includes('pageobjects') ||
+            fn.includes('actions') ||
+            fn.includes('steps') ||
+            fn.includes('hooks') ||
+            fn.includes('spectra.config')) {
+            triggerRegen(path.join(cwd, fn), eventType);
+        }
+    });
+    return {
+        watcher,
+        close: () => {
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            watcher.close();
+        },
     };
+}
+export async function watchCommand(options = {}) {
+    const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+    console.log(chalk.bold.cyan('\n🔭 TestSpectra Ambient Types Watcher'));
+    console.log(chalk.gray(`Watching workspace: ${cwd}\n`));
     try {
-        const watcher = fs.watch(cwd, { recursive: true }, (eventType, filename) => {
-            if (!filename)
-                return;
-            const fn = filename.toString();
-            if (fn.includes(".testspectra") ||
-                fn.includes("node_modules") ||
-                fn.includes(".git") ||
-                fn.includes("dist") ||
-                fn.includes(".nx")) {
-                return;
-            }
-            if (fn.includes("fixtures") ||
-                fn.includes("page-objects") ||
-                fn.includes("pageobjects") ||
-                fn.includes("actions") ||
-                fn.includes("steps") ||
-                fn.includes("hooks") ||
-                fn.includes("spectra.config")) {
-                triggerRegen(path.join(cwd, fn), eventType);
-            }
-        });
-        watcher.on("error", (err) => {
+        const handle = startWatcher(cwd, options.debounceMs ?? 60);
+        console.log(chalk.green('✔ Initialized ambient declarations in .testspectra/types/'));
+        console.log(chalk.gray('Press Ctrl+C to stop watching.\n'));
+        handle.watcher.on('error', (err) => {
             console.error(chalk.red(`Watcher error: ${err?.message}`));
         });
-        console.log(chalk.gray("Press Ctrl+C to stop watching.\n"));
     }
     catch (err) {
         console.error(chalk.red(`Failed to start workspace watcher: ${err?.message}`));

package/dist/config/loader.d.ts

@@ -1,4 +1,4 @@
-import { ConfigData } from "./schema.js";
+import { ConfigData } from './schema.js';
 export declare class ConfigLoader {
     static readonly CONFIG_FILE_NAMES: string[];
     static findConfigFile(cwd?: string): string | null;

package/dist/config/loader.js

@@ -1,14 +1,14 @@
-import fs from "fs";
-import path from "path";
-import { DEFAULT_CONFIG_DATA } from "./schema.js";
+import fs from 'fs';
+import path from 'path';
+import { DEFAULT_CONFIG_DATA } from './schema.js';
 export class ConfigLoader {
     static CONFIG_FILE_NAMES = [
-        "testspectra.config.ts",
-        "spectra.config.ts",
-        "testspectra.config.js",
-        "spectra.config.js",
-        "testspectra.config.json",
-        ".testspectrarc.json",
+        'testspectra.config.ts',
+        'spectra.config.ts',
+        'testspectra.config.js',
+        'spectra.config.js',
+        'testspectra.config.json',
+        '.testspectrarc.json',
     ];
     static findConfigFile(cwd = process.cwd()) {
         let cur = path.resolve(cwd);
@@ -30,16 +30,16 @@ export class ConfigLoader {
         const configPath = this.findConfigFile(cwd);
         let loaded = {};
         if (configPath) {
-            if (configPath.endsWith(".json")) {
+            if (configPath.endsWith('.json')) {
                 try {
-                    const raw = fs.readFileSync(configPath, "utf-8");
+                    const raw = fs.readFileSync(configPath, 'utf-8');
                     loaded = JSON.parse(raw);
                 }
                 catch (e) {
                     console.warn(`[TestSpectra] Warning: Failed to parse ${configPath}:`, e);
                 }
             }
-            else if (configPath.endsWith(".ts") || configPath.endsWith(".js")) {
+            else if (configPath.endsWith('.ts') || configPath.endsWith('.js')) {
                 try {
                     const fileUrl = new URL(`file://${path.resolve(configPath)}`).href;
                     const mod = await import(fileUrl);
@@ -56,31 +56,46 @@ export class ConfigLoader {
             ...overrides,
             webConfig: {
                 ...DEFAULT_CONFIG_DATA.webConfig,
-                ...(loaded.webConfig || {}),
-                ...(overrides?.webConfig || {}),
+                ...loaded.webConfig,
+                ...overrides?.webConfig,
             },
             androidConfig: {
                 ...DEFAULT_CONFIG_DATA.androidConfig,
-                ...(loaded.androidConfig || {}),
-                ...(overrides?.androidConfig || {}),
+                ...loaded.androidConfig,
+                ...overrides?.androidConfig,
             },
             iosConfig: {
                 ...DEFAULT_CONFIG_DATA.iosConfig,
-                ...(loaded.iosConfig || {}),
-                ...(overrides?.iosConfig || {}),
+                ...loaded.iosConfig,
+                ...overrides?.iosConfig,
             },
             executionConfig: {
-                networkMonitoringEnabled: overrides?.executionConfig?.networkMonitoringEnabled ?? loaded.executionConfig?.networkMonitoringEnabled ?? DEFAULT_CONFIG_DATA.executionConfig?.networkMonitoringEnabled ?? true,
-                fastResponseTime: overrides?.executionConfig?.fastResponseTime ?? loaded.executionConfig?.fastResponseTime ?? DEFAULT_CONFIG_DATA.executionConfig?.fastResponseTime ?? "200",
-                normalResponseTime: overrides?.executionConfig?.normalResponseTime ?? loaded.executionConfig?.normalResponseTime ?? DEFAULT_CONFIG_DATA.executionConfig?.normalResponseTime ?? "1000",
-                monitoredDomains: overrides?.executionConfig?.monitoredDomains ?? loaded.executionConfig?.monitoredDomains ?? DEFAULT_CONFIG_DATA.executionConfig?.monitoredDomains ?? [],
-                environmentVariables: overrides?.executionConfig?.environmentVariables ?? loaded.executionConfig?.environmentVariables ?? DEFAULT_CONFIG_DATA.executionConfig?.environmentVariables ?? [],
+                networkMonitoringEnabled: overrides?.executionConfig?.networkMonitoringEnabled ??
+                    loaded.executionConfig?.networkMonitoringEnabled ??
+                    DEFAULT_CONFIG_DATA.executionConfig?.networkMonitoringEnabled ??
+                    true,
+                fastResponseTime: overrides?.executionConfig?.fastResponseTime ??
+                    loaded.executionConfig?.fastResponseTime ??
+                    DEFAULT_CONFIG_DATA.executionConfig?.fastResponseTime ??
+                    '200',
+                normalResponseTime: overrides?.executionConfig?.normalResponseTime ??
+                    loaded.executionConfig?.normalResponseTime ??
+                    DEFAULT_CONFIG_DATA.executionConfig?.normalResponseTime ??
+                    '1000',
+                monitoredDomains: overrides?.executionConfig?.monitoredDomains ??
+                    loaded.executionConfig?.monitoredDomains ??
+                    DEFAULT_CONFIG_DATA.executionConfig?.monitoredDomains ??
+                    [],
+                environmentVariables: overrides?.executionConfig?.environmentVariables ??
+                    loaded.executionConfig?.environmentVariables ??
+                    DEFAULT_CONFIG_DATA.executionConfig?.environmentVariables ??
+                    [],
             },
         };
     }
-    static saveConfig(cwd, config, filename = "testspectra.config.json") {
+    static saveConfig(cwd, config, filename = 'testspectra.config.json') {
         const target = path.join(cwd, filename);
-        fs.writeFileSync(target, JSON.stringify(config, null, 2), "utf-8");
+        fs.writeFileSync(target, JSON.stringify(config, null, 2), 'utf-8');
         return target;
     }
 }

package/dist/config/schema.d.ts

@@ -9,14 +9,15 @@ export interface WebConfig {
     baseUrl: string;
     /**
      * Maximum number of parallel browser sessions/workers spawned during test execution.
-     * @default "1"
+     * Can be an explicit number, numeric string, or `"auto"`.
+     * @default "auto"
      */
-    maxConcurrentSessions: string;
+    maxConcurrentSessions: number | string | 'auto';
     /**
      * Whether to run browsers in headless mode without a visible GUI window.
      * @default true
      */
-    headlessMode: boolean;
+    headless: boolean | 'new';
     /**
      * Implicit wait timeout (in milliseconds) for finding elements before throwing an error.
      * @default "5000"
@@ -32,13 +33,18 @@ export interface WebConfig {
      * @default "30000"
      */
     scriptTimeout: string;
+    /**
+     * Delay between consecutive actions and commands in milliseconds (slow motion).
+     * @default 0
+     */
+    stepDelay?: number;
     /**
      * 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";
+    parallelizationMode: 'testcase' | 'suite';
 }
 /**
  * Browser target definition for web test execution.
@@ -72,34 +78,76 @@ export interface Browser {
     height?: string;
 }
 /**
- * Configuration for Android mobile test automation with Appium & UiAutomator2.
+ * Target Android device specification for multi-device parallel execution.
  */
-export interface AndroidConfig {
+export interface AndroidDeviceTarget {
     /**
-     * Appium server endpoint URL.
-     * @default "http://127.0.0.1:4723"
+     * ADB serial or device ID (e.g. "emulator-5554", "192.168.1.50:5555").
      */
-    appiumServer: string;
+    id: string;
     /**
-     * Mobile platform name.
-     * @default "Android"
+     * Emulator AVD name (e.g. "Pixel_7_Pro_API_34").
      */
-    platformName: string;
+    avd?: string;
     /**
-     * Android OS version (e.g. `"13"`, `"14"`).
-     * @default "13"
+     * Friendly display/model name (e.g. "Pixel 7 Pro").
      */
-    platformVersion: string;
+    name?: string;
     /**
-     * Target Android device name or ADB serial ID (e.g. `"emulator-5554"`).
-     * @default "emulator-5554"
+     * Android OS version (e.g. "14.0").
      */
-    deviceName: string;
+    version?: string;
     /**
-     * Appium mobile automation driver engine.
-     * @default "UiAutomator2"
+     * UiAutomator2 port (e.g. 8200).
      */
-    automationName: string;
+    systemPort?: number;
+    /**
+     * Custom Appium capabilities overrides for this specific device.
+     */
+    capabilities?: Record<string, any>;
+}
+/**
+ * Target iOS device specification for multi-device parallel execution.
+ */
+export interface IosDeviceTarget {
+    /**
+     * Device ID or simulator slug (e.g. "iphone-15-pro").
+     */
+    id: string;
+    /**
+     * Friendly name (e.g. "iPhone 15 Pro Simulator").
+     */
+    name?: string;
+    /**
+     * iOS version (e.g. "17.0").
+     */
+    version?: string;
+    /**
+     * Physical device UDID or "auto".
+     */
+    udid?: string;
+    /**
+     * WebDriverAgent local port (e.g. 8100).
+     */
+    wdaLocalPort?: number;
+    /**
+     * Custom Appium capabilities overrides for this specific device.
+     */
+    capabilities?: Record<string, any>;
+}
+/**
+ * Configuration for Android mobile test automation with Spectra Android Native Driver.
+ */
+export interface AndroidConfig {
+    /**
+     * Spectra Android Driver server endpoint URL.
+     * @default "tcp://127.0.0.1:8200"
+     */
+    driverServer?: string;
+    /**
+     * Legacy Appium server endpoint URL (fallback, deprecated — use `driverServer`).
+     */
+    appiumServer?: string;
     /**
      * Android application package name (e.g. `"com.example.app"`).
      */
@@ -120,39 +168,47 @@ export interface AndroidConfig {
     noReset: boolean;
     /**
      * Implicit wait timeout (in milliseconds) for locating mobile elements.
-     * @default "10000"
+     * @default 10000
      */
-    implicitWait: string;
+    implicitWait: string | number;
     /**
      * Parallelization execution mode for Android mobile tests.
      * @default "suite"
      */
-    parallelizationMode: "testcase" | "suite";
+    parallelizationMode: 'testcase' | 'suite';
+    /**
+     * Array of explicit target devices or configurations for multi-device parallel execution.
+     * Each entry can specify its own `id`, `name`, `version`, `avd`, `systemPort`, etc.
+     */
+    devices: (string | AndroidDeviceTarget)[] | 'auto';
+    /**
+     * Raw custom WebdriverIO / Appium capabilities array override.
+     */
+    capabilities?: Record<string, any>[];
+    /**
+     * Maximum concurrent mobile sessions/devices cap.
+     */
+    maxConcurrentSessions?: number | string;
+    /**
+     * Delay between consecutive actions and commands in milliseconds (slow motion).
+     * @default 0
+     */
+    stepDelay?: number;
 }
 /**
  * Configuration for iOS mobile test automation with Appium & XCUITest.
  */
 export interface IosConfig {
+    /**
+     * Delay between consecutive actions and commands in milliseconds (slow motion).
+     * @default 0
+     */
+    stepDelay?: number;
     /**
      * 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"
@@ -166,16 +222,28 @@ export interface IosConfig {
      * Target device Unique Device Identifier (UDID) or `"auto"`.
      * @default "auto"
      */
-    udid: string;
+    udid?: string;
+    /**
+     * Array of explicit target devices or configurations for multi-device execution.
+     */
+    devices: (string | IosDeviceTarget)[] | 'auto';
+    /**
+     * Raw custom WebdriverIO / Appium capabilities array override.
+     */
+    capabilities?: Record<string, any>[];
+    /**
+     * Maximum concurrent mobile sessions/devices cap.
+     */
+    maxConcurrentSessions?: number | string;
     /**
      * Apple Developer Team 10-character Organization ID for code signing.
      */
-    xcodeOrgId: string;
+    xcodeOrgId?: string;
     /**
      * Xcode code signing identity string (e.g. `"iPhone Developer"`).
      * @default "iPhone Developer"
      */
-    xcodeSigningId: string;
+    xcodeSigningId?: string;
     /**
      * Whether to automatically accept iOS system permission alerts.
      * @default true
@@ -188,14 +256,14 @@ export interface IosConfig {
     noReset: boolean;
     /**
      * Implicit wait timeout (in milliseconds) for locating iOS UI elements.
-     * @default "10000"
+     * @default 10000
      */
-    implicitWait: string;
+    implicitWait: string | number;
     /**
      * Parallelization execution mode for iOS mobile tests.
      * @default "suite"
      */
-    parallelizationMode: "testcase" | "suite";
+    parallelizationMode: 'testcase' | 'suite';
 }
 /**
  * Load testing stage ramp-up profile.
@@ -328,9 +396,9 @@ export interface ConfigData {
 /**
  * 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];
-};
+export type DeepPartial<T> = T extends Function | boolean | number | string | symbol | null | undefined ? T : T extends Array<infer U> ? DeepPartial<U>[] : T extends ReadonlyArray<infer U> ? readonly DeepPartial<U>[] : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
 /**
  * User-provided configuration options with optional deep partial properties.
  */
@@ -345,7 +413,7 @@ export type UserConfig = DeepPartial<ConfigData>;
  * export default defineConfig({
  *   webConfig: {
  *     baseUrl: "https://example.com",
- *     headlessMode: false,
+ *     headless: false,
  *   },
  * });
  * ```