@testspectra/cli 1.1.8-rc.9 → 1.1.11-rc.3

package/dist/utils/dependency-updates.js

@@ -0,0 +1,107 @@
+import { execFileSync } from 'child_process';
+import { runSystemChecks } from '../commands/doctor.js';
+const CHROME_FOR_TESTING_API = 'https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions.json';
+const BUN_RELEASES_API = 'https://api.github.com/repos/oven-sh/bun/releases/latest';
+const PLATFORM_TOOLS_XML = 'https://dl.google.com/android/repository/repository2-3.xml';
+function normalizeVersion(raw) {
+    if (!raw)
+        return null;
+    const match = raw.match(/(\d+\.\d+\.\d+(?:[-.][0-9A-Za-z.-]+)?)/);
+    return match ? match[1] : null;
+}
+async function fetchJson(url) {
+    try {
+        const res = await fetch(url, {
+            signal: AbortSignal.timeout(8000),
+            headers: { 'User-Agent': 'testspectra-cli' },
+        });
+        if (!res.ok)
+            return null;
+        return await res.json();
+    }
+    catch {
+        return null;
+    }
+}
+async function latestChromeVersion() {
+    const json = await fetchJson(CHROME_FOR_TESTING_API);
+    return json?.channels?.Stable?.version ?? null;
+}
+async function latestBunVersion() {
+    const json = await fetchJson(BUN_RELEASES_API);
+    const tag = json?.tag_name;
+    return typeof tag === 'string' ? tag.replace(/^bun-v/, '') : null;
+}
+async function latestAdbVersion() {
+    try {
+        const res = await fetch(PLATFORM_TOOLS_XML, {
+            signal: AbortSignal.timeout(8000),
+            headers: { 'User-Agent': 'testspectra-cli' },
+        });
+        if (!res.ok)
+            return null;
+        const xml = await res.text();
+        const block = xml.match(/<remotePackage[^>]*path="platform-tools"[\s\S]*?<\/remotePackage>/);
+        if (!block)
+            return null;
+        const rev = block[0].match(/<revision>[\s\S]*?<major>(\d+)<\/major>[\s\S]*?<minor>(\d+)<\/minor>[\s\S]*?<micro>(\d+)<\/micro>/);
+        return rev ? `${rev[1]}.${rev[2]}.${rev[3]}` : null;
+    }
+    catch {
+        return null;
+    }
+}
+function latestAndroidAgentVersion() {
+    try {
+        return (execFileSync('npm', ['view', '@testspectra/android-agent', 'version', '--json'], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 10000,
+        })
+            .toString()
+            .trim()
+            .replace(/"/g, '') || null);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Best-effort "installed vs latest" report for the managed system drivers and the Spectra Android
+ * Agent, keyed by the exact `name` `spectra doctor` reports so the VS Code Preflight panel can
+ * attach a per-row update badge. `latest` stays `null` when it cannot be determined (offline,
+ * private registry unavailable) — the row still exposes its reinstall action.
+ */
+export async function checkDriverUpdates() {
+    let installed;
+    try {
+        const result = await runSystemChecks();
+        installed = result.dependencies;
+    }
+    catch {
+        return [];
+    }
+    const [chrome, bun, adb] = await Promise.all([latestChromeVersion(), latestBunVersion(), latestAdbVersion()]);
+    const agent = latestAndroidAgentVersion();
+    const candidates = [
+        { name: 'Google Chrome', latest: chrome },
+        { name: 'Bun', latest: bun },
+        { name: 'ADB (Android Debug Bridge)', latest: adb },
+        { name: 'Spectra Android Agent', latest: agent },
+    ];
+    const updates = [];
+    for (const { name, latest } of candidates) {
+        const dep = installed.find((d) => d.name === name);
+        if (!dep?.installed)
+            continue;
+        const current = normalizeVersion(dep.version);
+        updates.push({
+            name,
+            kind: 'driver',
+            identifier: name,
+            current,
+            latest,
+            needsUpdate: !!latest && !!current && current !== latest,
+        });
+    }
+    return updates;
+}

package/dist/utils/dev-server-manager.d.ts

@@ -0,0 +1,40 @@
+import type { ChildProcess } from 'node:child_process';
+import type { DevServerConfig } from '../config/schema.js';
+export interface RunningDevServer {
+    name: string;
+    url: string;
+    process?: ChildProcess;
+    reused: boolean;
+}
+export declare class DevServerManager {
+    private spawnedProcesses;
+    private cleanupRegistered;
+    constructor();
+    /**
+     * Safely splits a shell command string into binary executable and argument array without shell expansion.
+     */
+    static parseCommand(command: string): {
+        bin: string;
+        args: string[];
+    };
+    /**
+     * Probes a URL to verify if the server is actively listening and responsive.
+     * Performs a rapid TCP connection test followed by an HTTP/HTTPS request.
+     */
+    static probeUrl(targetUrl: string, timeoutMs?: number): Promise<boolean>;
+    /**
+     * Ensures an individual dev server is running. If already responding and reuseExistingServer !== false,
+     * reuses the instance. Otherwise, spawns the process and polls until ready.
+     */
+    ensureServer(config: DevServerConfig, rootCwd?: string): Promise<RunningDevServer>;
+    /**
+     * Starts all matching dev servers in parallel.
+     */
+    startAll(configs?: DevServerConfig[], targetHostFilter?: string, rootCwd?: string): Promise<RunningDevServer[]>;
+    /**
+     * Safely terminates all spawned dev server child processes.
+     */
+    stopAll(): Promise<void>;
+    private killProcess;
+    private registerExitHooks;
+}

package/dist/utils/dev-server-manager.js

@@ -0,0 +1,257 @@
+import net from 'node:net';
+import http from 'node:http';
+import https from 'node:https';
+import path from 'node:path';
+import spawn from 'cross-spawn';
+export class DevServerManager {
+    spawnedProcesses = new Map();
+    cleanupRegistered = false;
+    constructor() {
+        this.registerExitHooks();
+    }
+    /**
+     * Safely splits a shell command string into binary executable and argument array without shell expansion.
+     */
+    static parseCommand(command) {
+        const trimmed = command.trim();
+        if (!trimmed) {
+            throw new Error('Dev server command cannot be empty');
+        }
+        const tokens = [];
+        let current = '';
+        let inQuotes = false;
+        let quoteChar = '';
+        for (let i = 0; i < trimmed.length; i++) {
+            const char = trimmed[i];
+            if ((char === '"' || char === "'") && (i === 0 || trimmed[i - 1] !== '\\')) {
+                if (inQuotes && char === quoteChar) {
+                    inQuotes = false;
+                    quoteChar = '';
+                }
+                else if (!inQuotes) {
+                    inQuotes = true;
+                    quoteChar = char;
+                }
+                else {
+                    current += char;
+                }
+            }
+            else if (/\s/.test(char) && !inQuotes) {
+                if (current.length > 0) {
+                    tokens.push(current);
+                    current = '';
+                }
+            }
+            else {
+                current += char;
+            }
+        }
+        if (current.length > 0) {
+            tokens.push(current);
+        }
+        const bin = tokens[0];
+        const args = tokens.slice(1);
+        return { bin, args };
+    }
+    /**
+     * Probes a URL to verify if the server is actively listening and responsive.
+     * Performs a rapid TCP connection test followed by an HTTP/HTTPS request.
+     */
+    static async probeUrl(targetUrl, timeoutMs = 1500) {
+        try {
+            const parsed = new URL(targetUrl);
+            const isHttps = parsed.protocol === 'https:';
+            const port = parsed.port ? parseInt(parsed.port, 10) : isHttps ? 443 : 80;
+            const hostname = parsed.hostname;
+            // 1. TCP Probe (Fast check)
+            const tcpReachable = await new Promise((resolve) => {
+                const socket = net.createConnection({ host: hostname, port, timeout: timeoutMs }, () => {
+                    socket.destroy();
+                    resolve(true);
+                });
+                socket.on('error', () => {
+                    socket.destroy();
+                    resolve(false);
+                });
+                socket.on('timeout', () => {
+                    socket.destroy();
+                    resolve(false);
+                });
+            });
+            if (!tcpReachable) {
+                return false;
+            }
+            // 2. HTTP/HTTPS Probe (Verify application readiness, bypass self-signed certs)
+            return await new Promise((resolve) => {
+                const transport = isHttps ? https : http;
+                const req = transport.request(targetUrl, {
+                    method: 'HEAD',
+                    timeout: timeoutMs,
+                    rejectUnauthorized: false,
+                }, (res) => {
+                    // Any valid HTTP response means server is alive and accepting traffic
+                    res.resume();
+                    resolve(true);
+                });
+                req.on('error', () => resolve(false));
+                req.on('timeout', () => {
+                    req.destroy();
+                    resolve(false);
+                });
+                req.end();
+            });
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Ensures an individual dev server is running. If already responding and reuseExistingServer !== false,
+     * reuses the instance. Otherwise, spawns the process and polls until ready.
+     */
+    async ensureServer(config, rootCwd = process.cwd()) {
+        const serverName = config.name || config.url;
+        const timeoutMs = config.timeout ?? 60000;
+        const reuse = config.reuseExistingServer !== false;
+        // Check if server is already running
+        if (reuse) {
+            const isRunning = await DevServerManager.probeUrl(config.url, 1000);
+            if (isRunning) {
+                console.log(`\x1b[36m[TestSpectra DevServer]\x1b[0m ⚡ Reusing active server \x1b[1m"${serverName}"\x1b[0m at \x1b[33m${config.url}\x1b[0m`);
+                return {
+                    name: serverName,
+                    url: config.url,
+                    reused: true,
+                };
+            }
+        }
+        console.log(`\x1b[36m[TestSpectra DevServer]\x1b[0m 🚀 Launching dev server \x1b[1m"${serverName}"\x1b[0m (\x1b[90m${config.command}\x1b[0m)...`);
+        const { bin, args } = DevServerManager.parseCommand(config.command);
+        const execCwd = config.cwd ? path.resolve(rootCwd, config.cwd) : rootCwd;
+        const logBuffer = [];
+        const pushLog = (data) => {
+            const lines = data.toString().split('\n');
+            for (const line of lines) {
+                if (line.trim()) {
+                    logBuffer.push(line);
+                    if (logBuffer.length > 50)
+                        logBuffer.shift();
+                }
+            }
+        };
+        const child = spawn(bin, args, {
+            cwd: execCwd,
+            env: { ...process.env, ...config.env },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: process.platform !== 'win32',
+        });
+        child.stdout?.on('data', pushLog);
+        child.stderr?.on('data', pushLog);
+        this.spawnedProcesses.set(serverName, {
+            child,
+            name: serverName,
+            url: config.url,
+            logBuffer,
+        });
+        const startTime = Date.now();
+        let isReady = false;
+        while (Date.now() - startTime < timeoutMs) {
+            if (child.exitCode !== null) {
+                const errorLogs = logBuffer.slice(-20).join('\n');
+                throw new Error(`Dev server "${serverName}" terminated prematurely with exit code ${child.exitCode}.\n` +
+                    `Last output:\n${errorLogs || '(no output)'}`);
+            }
+            isReady = await DevServerManager.probeUrl(config.url, 500);
+            if (isReady) {
+                const durationSec = ((Date.now() - startTime) / 1000).toFixed(1);
+                console.log(`\x1b[32m[TestSpectra DevServer] ✓ Server "${serverName}" ready at ${config.url} (${durationSec}s)\x1b[0m`);
+                return {
+                    name: serverName,
+                    url: config.url,
+                    process: child,
+                    reused: false,
+                };
+            }
+            await new Promise((r) => setTimeout(r, 200));
+        }
+        // Timeout exceeded — dump logs and kill child
+        this.killProcess(child);
+        this.spawnedProcesses.delete(serverName);
+        const errorLogs = logBuffer.slice(-25).join('\n');
+        throw new Error(`Dev server "${serverName}" timed out after ${timeoutMs}ms waiting for ${config.url}.\n` +
+            `Last output:\n${errorLogs || '(no output)'}`);
+    }
+    /**
+     * Starts all matching dev servers in parallel.
+     */
+    async startAll(configs = [], targetHostFilter, rootCwd = process.cwd()) {
+        if (!configs || configs.length === 0) {
+            return [];
+        }
+        let targetConfigs = configs;
+        if (targetHostFilter) {
+            const matched = configs.filter((c) => c.name === targetHostFilter);
+            if (matched.length > 0) {
+                targetConfigs = matched;
+            }
+        }
+        return Promise.all(targetConfigs.map((cfg) => this.ensureServer(cfg, rootCwd)));
+    }
+    /**
+     * Safely terminates all spawned dev server child processes.
+     */
+    async stopAll() {
+        if (this.spawnedProcesses.size === 0)
+            return;
+        for (const entry of this.spawnedProcesses.values()) {
+            try {
+                this.killProcess(entry.child);
+            }
+            catch { }
+        }
+        this.spawnedProcesses.clear();
+    }
+    killProcess(child) {
+        if (child.pid && !child.killed) {
+            if (process.platform !== 'win32') {
+                try {
+                    process.kill(-child.pid, 'SIGTERM');
+                }
+                catch {
+                    try {
+                        child.kill('SIGTERM');
+                    }
+                    catch { }
+                }
+            }
+            else {
+                try {
+                    child.kill('SIGTERM');
+                }
+                catch { }
+            }
+        }
+    }
+    registerExitHooks() {
+        if (this.cleanupRegistered)
+            return;
+        this.cleanupRegistered = true;
+        const cleanup = () => {
+            for (const entry of this.spawnedProcesses.values()) {
+                try {
+                    this.killProcess(entry.child);
+                }
+                catch { }
+            }
+        };
+        process.once('exit', cleanup);
+        process.once('SIGINT', () => {
+            cleanup();
+            process.exit(130);
+        });
+        process.once('SIGTERM', () => {
+            cleanup();
+            process.exit(143);
+        });
+    }
+}

package/dist/utils/update-notifier.d.ts

@@ -0,0 +1,2 @@
+export declare function checkUpdateInBackground(): void;
+export declare function displayUpdateNotificationIfNeeded(): void;

package/dist/utils/update-notifier.js

@@ -0,0 +1,67 @@
+import fs from 'fs';
+import path from 'path';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+export function checkUpdateInBackground() {
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    const spectraDir = path.join(home, '.testspectra');
+    const cachePath = path.join(spectraDir, 'update-cache.json');
+    try {
+        if (!fs.existsSync(spectraDir)) {
+            fs.mkdirSync(spectraDir, { recursive: true });
+        }
+        if (fs.existsSync(cachePath)) {
+            const stats = fs.statSync(cachePath);
+            const now = Date.now();
+            if (now - stats.mtimeMs < CACHE_TTL_MS) {
+                // Cache is still valid, don't spawn background check
+                return;
+            }
+        }
+    }
+    catch {
+        // Ignore fs errors
+    }
+    // Spawn background check
+    const checkerScript = path.join(__dirname, 'background-update-check.js');
+    if (fs.existsSync(checkerScript)) {
+        const child = spawn(process.execPath, [checkerScript, cachePath], {
+            detached: true,
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+        child.unref();
+    }
+}
+export function displayUpdateNotificationIfNeeded() {
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    const cachePath = path.join(home, '.testspectra', 'update-cache.json');
+    if (!fs.existsSync(cachePath))
+        return;
+    try {
+        const cache = JSON.parse(fs.readFileSync(cachePath, 'utf-8'));
+        if (cache.updatesAvailable && cache.updatesAvailable.length > 0) {
+            console.log('\n\x1b[33m╭─────────────────────────────────────────────────────────────────╮\x1b[0m');
+            console.log('\x1b[33m│\x1b[0m                                                                 \x1b[33m│\x1b[0m');
+            const pkg = cache.updatesAvailable[0];
+            const msg = `Update available: ${pkg.pkg} ${pkg.current ?? '0.0.0'} → ${pkg.latest}`;
+            const padding = Math.max(0, 63 - msg.length);
+            const padLeft = Math.floor(padding / 2);
+            const padRight = padding - padLeft;
+            console.log(`\x1b[33m│\x1b[0m${' '.repeat(padLeft)}\x1b[37m${msg}\x1b[0m${' '.repeat(padRight)}\x1b[33m│\x1b[0m`);
+            const cmdMsg = 'Run `spectra upgrade` to update CLI, Matchers, and Drivers';
+            const cmdPadding = Math.max(0, 63 - cmdMsg.length);
+            const cmdPadLeft = Math.floor(cmdPadding / 2);
+            const cmdPadRight = cmdPadding - cmdPadLeft;
+            console.log(`\x1b[33m│\x1b[0m${' '.repeat(cmdPadLeft)}\x1b[36m${cmdMsg}\x1b[0m${' '.repeat(cmdPadRight)}\x1b[33m│\x1b[0m`);
+            console.log('\x1b[33m│\x1b[0m                                                                 \x1b[33m│\x1b[0m');
+            console.log('\x1b[33m╰─────────────────────────────────────────────────────────────────╯\x1b[0m\n');
+        }
+    }
+    catch {
+        // Ignore errors reading cache
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@testspectra/cli",
-  "version": "1.1.8-rc.9",
-  "description": "TestSpectra Zero-Config Cross-Platform Test Runner CLI",
+  "version": "1.1.11-rc.3",
+  "description": "TestSpectra Cross-Platform Test Runner CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -26,11 +26,12 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@testspectra/matchers": "^1.1.8-rc.9",
-    "@testspectra/react": "^1.1.8-rc.9",
-    "@testspectra/skills": "^1.1.8-rc.9",
+    "@testspectra/matchers": "^1.1.11-rc.3",
+    "@testspectra/react": "^1.1.11-rc.3",
+    "@testspectra/skills": "^1.1.11-rc.3",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
+    "cross-spawn": "^7.0.6",
     "dotenv": "^16.4.5",
     "ora": "^8.0.1",
     "typescript": "^5.6.3",
@@ -38,12 +39,12 @@
     "zod": "^3.23.8"
   },
   "optionalDependencies": {
-    "@testspectra/cli-darwin-arm64": "1.1.8-rc.9",
-    "@testspectra/cli-linux-x64": "1.1.8-rc.9",
-    "@testspectra/cli-win32-arm64": "1.1.8-rc.9",
-    "@testspectra/cli-win32-x64": "1.1.8-rc.9"
+    "@testspectra/cli-darwin-arm64": "1.1.11-rc.3",
+    "@testspectra/cli-linux-x64": "1.1.11-rc.3",
+    "@testspectra/cli-win32-x64": "1.1.11-rc.3"
   },
   "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
     "@types/node": "^20.14.0",
     "@wdio/globals": "^9.24.0",
     "@wdio/mocha-framework": "^9.24.0",

package/templates/default/package.json

@@ -17,8 +17,8 @@
     "postinstall": "spectra sync-types"
   },
   "devDependencies": {
-    "@testspectra/cli": "^1.1.8-rc.9",
-    "@testspectra/matchers": "^1.1.8-rc.9",
+    "@testspectra/cli": "^1.1.11-rc.3",
+    "@testspectra/matchers": "^1.1.11-rc.3",
     "@types/node": "^20.14.0",
     "@wdio/cli": "^9.2.8",
     "@wdio/local-runner": "^9.2.8",

package/templates/docs/ARCHITECTURE.default.md

@@ -0,0 +1,26 @@
+# TestSpectra Project Architecture
+
+This project is built with the TestSpectra testing framework.
+
+## Structure & File Map
+- `./spectra.config.ts`: Typed runner configuration.
+- `./specs/`: Layered test cases (`specs/<Suite>/<CaseId>/` with `web.test.ts`, `android.test.ts`, `ios.test.ts`).
+- `./page-objects/`: Page Object models per platform.
+- `./support/steps/`: Business flows accessible globally via `Step.*`.
+- `./support/actions/`: Atomic actions accessible globally via `Spectra.*`.
+- `./fixtures/`: JSON fixtures accessible globally via `Fixture.*`.
+- `./global-hooks/`: Global suite lifecycle hooks.
+- `./.testspectra/`: Auto-generated ambient typings and local runtime cache.
+
+## Execution
+```bash
+# Run web test suite
+pnpm test
+
+# Run Android / iOS
+pnpm spectra run --target android
+pnpm spectra run --target ios
+
+# Type check
+pnpm type-check
+```