@testspectra/cli 1.1.8-rc.3 → 1.1.8-rc.31

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.3",
-  "description": "TestSpectra Zero-Config Cross-Platform Test Runner CLI",
+  "version": "1.1.8-rc.31",
+  "description": "TestSpectra Cross-Platform Test Runner CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -16,15 +16,6 @@
     "spectra": "./bin/spectra.js",
     "testspectra": "./bin/spectra.js"
   },
-  "scripts": {
-    "build:rust": "node scripts/ensure-runner-binary.js",
-    "prebuild": "node scripts/ensure-runner-binary.js",
-    "build": "tsc && node scripts/copy-demo.js",
-    "watch": "tsc -w",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "npm run build"
-  },
   "files": [
     "dist",
     "bin",
@@ -34,26 +25,41 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@clack/prompts": "catalog:",
-    "@testspectra/matchers": "^1.1.8-rc.3",
-    "@testspectra/react": "^1.1.8-rc.3",
-    "@testspectra/skills": "^1.1.8-rc.3",
-    "chalk": "catalog:",
-    "commander": "catalog:",
-    "dotenv": "catalog:",
-    "ora": "catalog:",
-    "typescript": "catalog:",
-    "yaml": "catalog:",
-    "zod": "catalog:"
+    "@clack/prompts": "^1.7.0",
+    "@testspectra/matchers": "^1.1.8-rc.31",
+    "@testspectra/react": "^1.1.8-rc.31",
+    "@testspectra/skills": "^1.1.8-rc.31",
+    "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",
+    "yaml": "^2.7.0",
+    "zod": "^3.23.8"
+  },
+  "optionalDependencies": {
+    "@testspectra/cli-darwin-arm64": "1.1.8-rc.31",
+    "@testspectra/cli-linux-x64": "1.1.8-rc.31",
+    "@testspectra/cli-win32-x64": "1.1.8-rc.31"
   },
   "devDependencies": {
-    "@types/node": "catalog:",
-    "@wdio/globals": "catalog:",
-    "@wdio/mocha-framework": "catalog:",
-    "@wdio/types": "catalog:",
-    "esbuild": "catalog:",
-    "vitest": "catalog:"
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^20.14.0",
+    "@wdio/globals": "^9.24.0",
+    "@wdio/mocha-framework": "^9.24.0",
+    "@wdio/types": "^9.24.0",
+    "esbuild": "^0.28.2",
+    "vitest": "^2.1.8"
   },
   "type": "module",
-  "license": "SEE LICENSE IN LICENSE.md"
-}
+  "license": "SEE LICENSE IN LICENSE.md",
+  "scripts": {
+    "build:rust": "node scripts/ensure-runner-binary.js",
+    "prebuild": "node scripts/ensure-runner-binary.js",
+    "build": "tsc && node scripts/copy-demo.js",
+    "watch": "tsc -w",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/templates/default/CLAUDE.md

@@ -1,16 +1,16 @@
-# CLAUDE.md - TestSpectra Framework Conventions
-
-## Commands
-- Run all Web tests: `pnpm test:web` (or `spectra run -t web`)
-- Run all Mobile tests: `pnpm test:mobile` (or `spectra run -t mobile`)
-- Run Android tests: `pnpm test:android` (or `spectra run -t android`)
-- Run iOS tests: `pnpm test:ios` (or `spectra run -t ios`)
-- Run specific spec: `spectra run "specs/Playground/TC-0001-form-controls/mobile.test.ts" -t mobile`
-- Type checking: `pnpm type-check` (or `tsc -b`)
-- Preflight doctor: `pnpm doctor` (or `spectra doctor`)
-- Sync ambient types: `pnpm sync-types`
-
-## Element Selectors
-- `~name` → **accessibility id** (Android `content-desc`, RN `accessibilityLabel`, web `aria-label`) — the portable default.
-- `#name` → **native id** (Android `resource-id`, RN `testID`, web CSS `id`).
-- Each prefix maps to exactly one attribute (no silent cross-matching). Prefer `~` for user-perceivable elements, `#` for stable test ids. See `docs/v2/cli/selectors.md`.
+# CLAUDE.md - TestSpectra Framework Conventions
+
+## Commands
+- Run all Web tests: `pnpm test:web` (or `spectra run -t web`)
+- Run all Mobile tests: `pnpm test:mobile` (or `spectra run -t mobile`)
+- Run Android tests: `pnpm test:android` (or `spectra run -t android`)
+- Run iOS tests: `pnpm test:ios` (or `spectra run -t ios`)
+- Run specific spec: `spectra run "specs/Playground/TC-0001-form-controls/mobile.test.ts" -t mobile`
+- Type checking: `pnpm type-check` (or `tsc -b`)
+- Preflight doctor: `pnpm doctor` (or `spectra doctor`)
+- Sync ambient types: `pnpm sync-types`
+
+## Element Selectors
+- `~name` → **accessibility id** (Android `content-desc`, RN `accessibilityLabel`, web `aria-label`) — the portable default.
+- `#name` → **native id** (Android `resource-id`, RN `testID`, web CSS `id`).
+- Each prefix maps to exactly one attribute (no silent cross-matching). Prefer `~` for user-perceivable elements, `#` for stable test ids. See `docs/v2/cli/selectors.md`.

package/templates/default/global-hooks/after/mobile.hook.ts

@@ -1,3 +1,3 @@
-export default async function () {
-  // Global mobile teardown
-}
+export default async function () {
+  // Global mobile teardown
+}

package/templates/default/global-hooks/after/web.hook.ts

@@ -1,3 +1,3 @@
-export default async function () {
-  // Global web teardown
-}
+export default async function () {
+  // Global web teardown
+}

package/templates/default/global-hooks/before/mobile.hook.ts

@@ -1,3 +1,3 @@
-export default async function () {
-  // Global mobile initialization
-}
+export default async function () {
+  // Global mobile initialization
+}

package/templates/default/global-hooks/before/web.hook.ts

@@ -1,3 +1,3 @@
-export default async function () {
-  // Global web initialization
-}
+export default async function () {
+  // Global web initialization
+}

package/templates/default/package.json

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

package/templates/default/page-objects/AuthPage/mobile.ts

@@ -1,5 +1,5 @@
-class AuthPage {
-  get statusBadge() { return Spectra.get("~auth-status-badge"); }
-}
-
-export default new AuthPage();
+class AuthPage {
+  get statusBadge() { return Spectra.get("~auth-status-badge"); }
+}
+
+export default new AuthPage();

package/templates/default/page-objects/AuthPage/web.ts

@@ -1,10 +1,10 @@
-class AuthPage {
-  get checkStatusButton() { return Spectra.get("#check-auth-status-btn"); }
-  get statusBadge() { return Spectra.get("#auth-status-badge"); }
-
-  async open() {
-    await Spectra.navigate("/#auth");
-  }
-}
-
-export default new AuthPage();
+class AuthPage {
+  get checkStatusButton() { return Spectra.get("#check-auth-status-btn"); }
+  get statusBadge() { return Spectra.get("#auth-status-badge"); }
+
+  async open() {
+    await Spectra.navigate("/#auth");
+  }
+}
+
+export default new AuthPage();