@testspectra/cli 1.1.8-rc.9 → 1.1.10

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.10",
+  "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.10",
+    "@testspectra/react": "^1.1.10",
+    "@testspectra/skills": "^1.1.10",
     "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.10",
+    "@testspectra/cli-linux-x64": "1.1.10",
+    "@testspectra/cli-win32-x64": "1.1.10"
   },
   "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.10",
+    "@testspectra/matchers": "^1.1.10",
     "@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
+```

package/templates/docs/ARCHITECTURE.nx.md

@@ -0,0 +1,147 @@
+# TestSpectra Enterprise Monorepo Architecture
+
+This workspace uses TestSpectra's **"Centralized Configuration, Distributed Implementation"** model for automated cross-platform testing.
+
+---
+
+## 1. Directory & File Overview
+
+### Centralized Root Elements
+- `./spectra.config.ts`: Single source of truth for runtime configurations (Base URL, Appium devices, browser targets, timeouts).
+- `./.testspectra/`: Local test project cache, runtime metadata, auto-generated master TSConfig (`.testspectra/tsconfig.json`), platform sub-configs (`.testspectra/tsconfig/`), and universal ambient types (`.testspectra/types/`). Global binaries and drivers are managed at `~/.testspectra/drivers/`.
+- `./nx.json`: Nx target defaults with execution caching and inputs.
+- `./pnpm-workspace.yaml`: Monorepo package glob definitions.
+- `./tsconfig.json`: Solution-style TypeScript orchestrator referencing `./.testspectra/tsconfig.json`.
+
+### Centralized Shared Testing Library (`./__SHARED_TESTING_REL_PATH__`)
+Provides cross-feature reusable test entities with **100% zero-import global resolution**:
+- `page-objects/`: Shared Page Object models (e.g. NavigationBar, AppHeader).
+- `support/steps/`: Cross-feature business step flows (e.g. `Step.loginAsAdmin()`).
+- `support/actions/`: Custom atomic actions (e.g. `Spectra.dismissBanner()`).
+- `fixtures/`: Common test data and environment configurations (e.g. `Fixture.appConfig`).
+
+### Distributed Feature E2E Modules (__FEATURE_COUNT__ Features)
+__FEATURE_MODULES_SECTION__
+
+---
+
+## 2. Zero-Import Consumption Flow & Mechanics
+
+TestSpectra completely eliminates boilerplate `import` statements across all test specs, steps, and page objects.
+
+### How It Works:
+1. **Centralized Ambient Aggregation**:  
+   TestSpectra Language Service Plugin & CLI automatically scan:
+   - **Local Feature Entities**: `<feature>/__E2E_FOLDER_NAME__/page-objects/`, `<feature>/__E2E_FOLDER_NAME__/support/steps/`, `<feature>/__E2E_FOLDER_NAME__/support/actions/`
+   - **Shared Library Entities**: `./__SHARED_TESTING_REL_PATH__/page-objects/`, `./__SHARED_TESTING_REL_PATH__/support/steps/`, `./__SHARED_TESTING_REL_PATH__/support/actions/`, `./__SHARED_TESTING_REL_PATH__/fixtures/`
+2. **Ambient Typing Generation**:  
+   These are compiled into `.testspectra/types/web.d.ts`, `android.d.ts`, `ios.d.ts`, `fixtures.d.ts`.
+3. **Instant IDE Autocomplete & Zero Clutter**:  
+   Specs consume both local feature objects and shared library utilities globally.
+
+### Code Example:
+```typescript
+// packages/features/auth/e2e/specs/Auth/TC-AUTH-01/web.test.ts
+// 🌟 NOTICE: 100% Zero-Import & Flat Execution! (No import statement, no describe wrapper)
+
+it("should navigate via shared header and login with local POM", async () => {
+  // 1. Consumed from Shared Testing Library (__SHARED_TESTING_REL_PATH__/page-objects/NavigationBar)
+  await NavigationBar.goToLogin();
+
+  // 2. Consumed from Shared Testing Library (__SHARED_TESTING_REL_PATH__/support/steps/loginAsAdmin)
+  await Step.loginAsAdmin();
+
+  // 3. Consumed from Local Feature POM (page-objects/LoginPage)
+  await LoginPage.flashAlert.shouldBeVisible();
+  await LoginPage.flashAlert.shouldContainText("Welcome");
+
+  // 4. Consumed from Shared Testing Library Custom Action (__SHARED_TESTING_REL_PATH__/support/actions/dismissBanner)
+  await Spectra.dismissBanner();
+});
+```
+
+---
+
+## 3. How to Run Tests
+
+You can execute tests either from the **Monorepo Root via Nx** or directly inside each **Feature Directory via CLI**:
+
+### Option A: From Root Monorepo via Nx (Recommended for CI & Team Workflows)
+
+```bash
+# 1. Run E2E for a SPECIFIC feature module (e.g. auth)
+pnpm nx run auth-__E2E_FOLDER_NAME__:e2e
+
+# 2. Run E2E for a specific feature on ANDROID or IOS
+pnpm nx run auth-__E2E_FOLDER_NAME__:e2e --configuration=android
+pnpm nx run auth-__E2E_FOLDER_NAME__:e2e --configuration=ios
+
+# 3. Run E2E for a specific feature in HEADLESS browser mode
+pnpm nx run auth-__E2E_FOLDER_NAME__:e2e --configuration=headless
+
+# 4. Run ALL feature E2E suites across the entire monorepo in parallel
+pnpm nx run-many -t e2e
+
+# 5. Run only E2E tests for features modified in current Git branch / PR
+pnpm nx affected -t e2e
+```
+
+### Option B: Directly via TestSpectra CLI (`spectra run`)
+
+You can execute tests directly via CLI from either the **Monorepo Root** or inside a **Feature Directory**.  
+*Zero file-path overhead: You do NOT need to provide long file globs like `"packages/features/auth/**/*.spec.web.ts"` — just specify the TC ID or Suite name directly.*
+
+```bash
+# === From Monorepo Root ===
+
+# 1. Run ALL tests across the entire monorepo
+# (Spawns configured dev servers in parallel, checks readiness, runs tests, tears down)
+pnpm spectra run
+
+# 2. Run all tests for a specific host / dev server
+pnpm spectra run --host sso
+
+# 3. Run a specific test case by ID (simple TC ID, no long file path needed)
+pnpm spectra run --host sso --spec TC-AUTH-01
+
+# Or as a direct positional argument:
+pnpm spectra run --host sso TC-AUTH-01
+
+# 4. Run an entire suite by suite name
+pnpm spectra run --host sso --spec Auth
+# Or:
+pnpm spectra run --host sso Auth
+
+# 5. Run in Headed mode (visible Chrome window)
+pnpm spectra run --host sso --headed
+
+# === From Inside Feature Directory (cd __SAMPLE_FEATURE_E2E_PATH__) ===
+
+# Run all specs in this feature
+pnpm spectra run
+
+# Run a specific test case by ID
+pnpm spectra run TC-AUTH-01 -t web
+
+# Run a specific suite by name
+pnpm spectra run Auth -t web
+
+# Target Android device or emulator
+pnpm spectra run -t android
+
+# Target iOS simulator or device
+pnpm spectra run -t ios
+```
+
+---
+
+## 4. Type Checking & Validation
+
+```bash
+# Type check all E2E projects via Nx
+pnpm nx run-many -t type-check
+
+# Or standard TypeScript project references build from root
+pnpm type-check
+# or: npx tsc -b
+```