@testspectra/cli 1.2.12 → 1.2.14

package/dist/generator/type-generator.js

@@ -3,6 +3,7 @@ import path from 'path';
 import { createRequire } from 'node:module';
 import { ConfigLoader } from '../config/loader.js';
 import { TsConfigGenerator } from './tsconfig-generator.js';
+import { collectPageObjectEntries, renderPageObjectDeclarations } from './page-object-declarations.js';
 export const PLATFORM_HIERARCHY = {
     web: ['web', 'common'],
     android: ['android', 'mobile', 'common'],
@@ -178,23 +179,27 @@ export function discoverEntityScopes(cwd) {
     fallbackScan(cwd, 5);
     return scopes;
 }
-/**
- * Detects a component-testing project (`@testspectra/react`'s Vitest browser-mode runner), via
- * the same signal `cli/src/commands/test.ts` uses to gate `spectra test` itself. Used to augment
- * the generated `Spectra` ambient type with `.mount()`, which only exists in that runtime.
- */
-export function isComponentTestingProject(cwd) {
+export function detectComponentTesting(cwd) {
     try {
         const pkgPath = path.join(cwd, 'package.json');
         if (!fs.existsSync(pkgPath))
-            return false;
+            return { isComponent: false, isWebComponent: false, isMobileComponent: false };
         const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-        return Boolean(pkg.dependencies?.['@testspectra/react'] || pkg.devDependencies?.['@testspectra/react']);
+        const isWebComponent = Boolean(pkg.dependencies?.['@testspectra/react'] || pkg.devDependencies?.['@testspectra/react']);
+        const isMobileComponent = Boolean(pkg.dependencies?.['@testspectra/react-native'] || pkg.devDependencies?.['@testspectra/react-native']);
+        return {
+            isComponent: isWebComponent || isMobileComponent,
+            isWebComponent,
+            isMobileComponent,
+        };
     }
     catch {
-        return false;
+        return { isComponent: false, isWebComponent: false, isMobileComponent: false };
     }
 }
+export function isComponentTestingProject(cwd) {
+    return detectComponentTesting(cwd).isComponent;
+}
 /** Platform stems a plugin may expose as `exports` subpaths. */
 const PLUGIN_STEMS = ['web', 'android', 'ios', 'mobile', 'common'];
 /**
@@ -236,15 +241,23 @@ function resolvePluginPackageJson(cwd, specifier) {
         }
         return null;
     }
+    // A subpath specifier (`@scope/pkg/plugin`) resolves to its owning package, so its root
+    // augmentations and platform stems are wired exactly as for the root specifier.
+    const packageName = pluginPackageName(specifier);
     try {
         const req = createRequire(path.join(cwd, 'package.json'));
-        return walkUpToPackageJson(req.resolve(specifier));
+        return walkUpToPackageJson(req.resolve(packageName));
     }
     catch {
-        const fallback = path.join(cwd, 'node_modules', specifier, 'package.json');
+        const fallback = path.join(cwd, 'node_modules', packageName, 'package.json');
         return fs.existsSync(fallback) ? fallback : null;
     }
 }
+/** Maps a bare plugin specifier to its package name: `@scope/pkg/sub` → `@scope/pkg`, `pkg/sub` → `pkg`. */
+function pluginPackageName(specifier) {
+    const segments = specifier.split('/');
+    return specifier.startsWith('@') ? segments.slice(0, 2).join('/') : segments[0];
+}
 /**
  * Resolves each configured plugin to its package name + available platform stems.
  * Unresolvable plugins are skipped (the runtime loader reports them separately).
@@ -416,7 +429,7 @@ export class TypeGenerator {
         const poDirs = this.getPageObjectsDirsForScope(scopeDir, sharedDir);
         const actionsDirs = this.getEntityDirsForScope('actions', scopeDir, sharedDir);
         const stepsDirs = this.getEntityDirsForScope('steps', scopeDir, sharedDir);
-        const isComponentTesting = isComponentTestingProject(cwd);
+        const compInfo = detectComponentTesting(cwd);
         const platforms = ['web', 'android', 'ios', 'mobile', 'common'];
         const results = {
             web: '',
@@ -449,83 +462,17 @@ export class TypeGenerator {
             // forbids authoring it, so leaving it undeclared makes that a compile error too, not just a
             // lint error.
             content += `declare function it(title: string, fn: () => Promise<void> | void): void;\n`;
-            if (isComponentTesting) {
-                // Vitest's own `expect` global (test.globals: true in tools/react/vitest.config.ts) — the
-                // one thing component specs legitimately need beyond the Spectra.* DSL, for asserting
-                // plain closure/callback state (e.g. "was this onClick handler invoked") that has no DOM
-                // element to target. Reuses @testspectra/react's own re-exported `ExpectStatic` type
-                // rather than hand-duplicating Vitest's expect API surface. Not declared for E2E projects
-                // — the Rust orchestrator's BDD runtime has no `expect` global at all.
+            if (compInfo.isWebComponent && (platform === 'web' || platform === 'common')) {
                 content += `declare const expect: import('@testspectra/react').ExpectStatic;\n`;
             }
-            content += `\n`;
-            // 1. Page Objects Global Declarations
-            const declaredPOMs = new Set();
-            for (const poDir of poDirs) {
-                if (!fs.existsSync(poDir))
-                    continue;
-                const poEntries = fs.readdirSync(poDir, { withFileTypes: true });
-                for (const entry of poEntries) {
-                    if (entry.name.startsWith('.'))
-                        continue;
-                    if (entry.isDirectory()) {
-                        const className = entry.name;
-                        if (declaredPOMs.has(className))
-                            continue;
-                        const classFolder = path.join(poDir, className);
-                        let matchedFile = null;
-                        for (const stem of hierarchy) {
-                            const candidates = [
-                                path.join(classFolder, `${stem}.ts`),
-                                path.join(classFolder, `${stem}.page.ts`),
-                                path.join(classFolder, `${stem}.po.ts`),
-                            ];
-                            if (stem === 'common') {
-                                candidates.push(path.join(classFolder, 'common.ts'));
-                                candidates.push(path.join(classFolder, 'index.ts'));
-                            }
-                            for (const cand of candidates) {
-                                if (fs.existsSync(cand)) {
-                                    matchedFile = path.relative(outputTypesDir, cand).replace(/\\/g, '/').replace(/\.ts$/, '.js');
-                                    if (!matchedFile.startsWith('.'))
-                                        matchedFile = `./${matchedFile}`;
-                                    break;
-                                }
-                            }
-                            if (matchedFile)
-                                break;
-                        }
-                        if (matchedFile) {
-                            content += `declare const ${className}: (typeof import('${matchedFile}') extends { default: infer T } ? T : typeof import('${matchedFile}'));\n`;
-                            declaredPOMs.add(className);
-                        }
-                    }
-                    else if (entry.isFile() && entry.name.endsWith('.ts')) {
-                        const parts = entry.name.split('.');
-                        const className = parts[0];
-                        if (declaredPOMs.has(className))
-                            continue;
-                        let isMatch = false;
-                        if (parts.length === 2) {
-                            isMatch = true;
-                        }
-                        else if (parts.length > 2) {
-                            const stem = parts[1];
-                            isMatch = hierarchy.includes(stem);
-                        }
-                        if (isMatch) {
-                            let rel = path
-                                .relative(outputTypesDir, path.join(poDir, entry.name))
-                                .replace(/\\/g, '/')
-                                .replace(/\.ts$/, '.js');
-                            if (!rel.startsWith('.'))
-                                rel = `./${rel}`;
-                            content += `declare const ${className}: (typeof import('${rel}') extends { default: infer T } ? T : typeof import('${rel}'));\n`;
-                            declaredPOMs.add(className);
-                        }
-                    }
-                }
+            else if (compInfo.isMobileComponent &&
+                (platform === 'mobile' || platform === 'android' || platform === 'ios' || platform === 'common')) {
+                content += `declare const expect: import('@testspectra/react-native').ExpectStatic;\n`;
             }
+            content += `\n`;
+            // 1. Page Objects: flat ones as globals, every one also under `Page.<namespace>.<name>`
+            const poEntries = poDirs.flatMap((poDir) => collectPageObjectEntries(poDir, hierarchy));
+            content += renderPageObjectDeclarations(poEntries, outputTypesDir, cwd);
             // 2. Built-in Spectra Static Methods & Custom Actions
             content += `interface TestSpectraCustomActions {\n`;
             const declaredActions = new Set();
@@ -595,9 +542,24 @@ export class TypeGenerator {
                 }
             }
             content += `}\n`;
-            // Reuses @testspectra/react's own exported `mount` type rather than hand-duplicating its
-            // signature here — stays in sync automatically if that signature ever changes.
-            const mountAugment = isComponentTesting ? ` & { mount: typeof import('@testspectra/react').mount }` : '';
+            // Reuses @testspectra/react or @testspectra/react-native's own exported `mount` type rather than
+            // hand-duplicating its signature here — stays in sync automatically if that signature ever changes.
+            let mountPkg = null;
+            if (compInfo.isMobileComponent && (platform === 'android' || platform === 'ios' || platform === 'mobile')) {
+                mountPkg = '@testspectra/react-native';
+            }
+            else if (compInfo.isWebComponent && platform === 'web') {
+                mountPkg = '@testspectra/react';
+            }
+            else if (compInfo.isMobileComponent) {
+                mountPkg = '@testspectra/react-native';
+            }
+            else if (compInfo.isWebComponent) {
+                mountPkg = '@testspectra/react';
+            }
+            const mountAugment = mountPkg
+                ? ` & { mount: typeof import('${mountPkg}').mount; expect: import('${mountPkg}').ExpectStatic }`
+                : '';
             content += `type TestSpectraActions = import('@testspectra/matchers').SpectraStatic & TestSpectraCustomActions${mountAugment};\n`;
             content += `declare const Spectra: TestSpectraActions;\n\n`;
             // 3. Built-in Steps Declaration

package/dist/index.js

@@ -32,6 +32,7 @@ export function createCliProgram() {
         .description('Initialize spectra.config.ts and project directories')
         .option('-t, --template <template>', 'Project template: default, nx, react-component')
         .option('-f, --force', 'Overwrite existing configuration if present')
+        .option('--no-demo', 'Skip the demo plugin, demo specs/page objects/fixtures and WebdriverIO (template default only)')
         .action(initCommand);
     program
         .command('add [module]')
@@ -199,8 +200,9 @@ Examples:
         .action(runCommand);
     program
         .command('test')
-        .description('Run React component tests via the native CDP engine')
+        .description('Run React / React Native component tests via the native CDP engine or mobile harness')
         .option('-w, --cwd <dir>', 'Custom workspace directory')
+        .option('-t, --platform <platform>', 'Target platform: web (default), android, or mobile')
         .option('-s, --spec <path>', 'Spec file path (or substring filter) to execute')
         .option('--failed [targets]', 'Re-run failed tests from previous run (accepts comma-separated test IDs or spec paths)')
         .option('--headless', 'Run in headless mode (default)')

package/dist/linter/spec-linter.js

@@ -25,6 +25,29 @@ function resolvesToAmbientGlobalDir(specifier, testFilePath) {
         segments.includes('fixtures') ||
         (segments.includes('support') && segments.includes('steps')));
 }
+/**
+ * Classifies a directory entry as a file or a directory. A symbolic link is classified by its target
+ * (`fs.statSync` follows the link), so a linked `spec.md` or linked folder is linted like a real one.
+ * A dangling link, or one pointing at something that is neither, yields `null`.
+ */
+function entryKind(dir, entry) {
+    if (entry.isSymbolicLink()) {
+        try {
+            const target = fs.statSync(path.join(dir, entry.name));
+            if (target.isDirectory())
+                return 'directory';
+            if (target.isFile())
+                return 'file';
+        }
+        catch { }
+        return null;
+    }
+    if (entry.isDirectory())
+        return 'directory';
+    if (entry.isFile())
+        return 'file';
+    return null;
+}
 export class SpecLinter {
     /**
      * Validates a single spec.md file.
@@ -122,7 +145,7 @@ export class SpecLinter {
         try {
             const entries = fs.readdirSync(specDir, { withFileTypes: true });
             companionTestFiles = entries
-                .filter((e) => e.isFile() &&
+                .filter((e) => entryKind(specDir, e) === 'file' &&
                 (e.name.endsWith('.test.ts') ||
                     e.name.endsWith('.test.tsx') ||
                     e.name.endsWith('.web.ts') ||
@@ -418,12 +441,19 @@ export class SpecLinter {
                     suiteFiles.push(rootScan);
             }
             else {
-                // Directory traversal
+                // Directory traversal. Symlinks are followed (classified by their target); `visited` holds the
+                // real path of every folder already walked, so a link cycle cannot recurse forever.
+                const visited = new Set();
                 const traverse = (dir) => {
+                    const realDir = fs.realpathSync(dir);
+                    if (visited.has(realDir))
+                        return;
+                    visited.add(realDir);
                     const entries = fs.readdirSync(dir, { withFileTypes: true });
                     for (const entry of entries) {
                         const fullPath = path.join(dir, entry.name);
-                        if (entry.isDirectory()) {
+                        const kind = entryKind(dir, entry);
+                        if (kind === 'directory') {
                             if (entry.name === 'node_modules' ||
                                 entry.name === 'dist' ||
                                 entry.name === '.git' ||
@@ -432,7 +462,7 @@ export class SpecLinter {
                             }
                             traverse(fullPath);
                         }
-                        else if (entry.isFile()) {
+                        else if (kind === 'file') {
                             if (entry.name === 'spec.md') {
                                 specFiles.push(fullPath);
                             }

package/dist/refactor/refactor-engine.js

@@ -20,6 +20,10 @@ export const ENTITY_NAMING_RULES = {
     },
 };
 export const SUPPORTED_FIXTURE_EXTENSIONS = ['.json', '.csv', '.yaml', '.yml', '.ts', '.js'];
+/** Display symbol of a page object: the bare name when flat, `Page.<Namespace>.<name>` when nested. */
+function pageSymbol(name) {
+    return name.includes('/') ? `Page.${name.split('/').join('.')}` : name;
+}
 export class RefactorEngine {
     /**
      * Deterministically parses testing entity type and symbol name from a filesystem path.
@@ -30,11 +34,14 @@ export class RefactorEngine {
             return null;
         const normalized = filePath.replace(/\\/g, '/').replace(/\/+$/, '');
         const parts = normalized.split('/').filter(Boolean);
-        // 1. Page Objects: page-objects/<name> or page-objects/<name>/web.ts or page-objects/<name>.ts
+        // 1. Page Objects: page-objects/<name>, page-objects/<name>/web.ts, page-objects/<name>.ts, or a nested
+        // page-objects/<Namespace>/<name>[/web.ts] whose symbol is the path "<Namespace>/<name>".
         const poIdx = parts.findIndex((p) => p === 'page-objects');
         if (poIdx !== -1 && poIdx + 1 < parts.length) {
-            const rawSymbol = parts[poIdx + 1];
-            const symbol = path.parse(rawSymbol).name;
+            const segments = parts.slice(poIdx + 1);
+            const lastSegment = segments[segments.length - 1];
+            const folders = segments.length > 1 && path.extname(lastSegment) ? segments.slice(0, -1) : segments;
+            const symbol = folders.length === 1 ? path.parse(folders[0]).name : folders.join('/');
             if (symbol)
                 return { type: 'page-object', symbol };
         }
@@ -178,7 +185,9 @@ export class RefactorEngine {
             }
         }
         const rule = ENTITY_NAMING_RULES[type];
-        if (rule && !rule.regex.test(targetNewName)) {
+        // A page object may be nested ("GlobalSettings/Brand/List"): every folder segment follows the rule.
+        const nameSegments = type === 'page-object' ? targetNewName.split('/') : [targetNewName];
+        if (rule && !nameSegments.every((segment) => rule.regex.test(segment))) {
             return {
                 status: 'failed',
                 entityType: type,
@@ -189,6 +198,12 @@ export class RefactorEngine {
                 error: `Invalid new symbol name "${targetNewName}". Symbol name for ${type} must follow ${rule.convention}.`,
             };
         }
+        const oldSegments = targetOldName.split('/');
+        const newSegments = targetNewName.split('/');
+        const oldLeaf = oldSegments[oldSegments.length - 1];
+        const newLeaf = newSegments[newSegments.length - 1];
+        const isNestedPageObject = type === 'page-object' && oldSegments.length > 1;
+        const poSourceDir = path.join(workspaceRoot, 'page-objects', ...oldSegments);
         // Phase 1: Determine file operations and replacement patterns
         const plannedRenames = [];
         const plannedEdits = [];
@@ -222,10 +237,10 @@ export class RefactorEngine {
         }
         // 1. Target Directory / File Discovery for Source Entity
         if (type === 'page-object') {
-            oldSymbol = targetOldName;
-            newSymbol = targetNewName;
-            const targetPoDir = path.join(workspaceRoot, 'page-objects', targetNewName);
-            const poDir = path.join(workspaceRoot, 'page-objects', targetOldName);
+            oldSymbol = pageSymbol(targetOldName);
+            newSymbol = pageSymbol(targetNewName);
+            const targetPoDir = path.join(workspaceRoot, 'page-objects', ...targetNewName.split('/'));
+            const poDir = path.join(workspaceRoot, 'page-objects', ...targetOldName.split('/'));
             if (fs.existsSync(poDir)) {
                 plannedRenames.push({ from: poDir, to: targetPoDir });
             }
@@ -318,33 +333,46 @@ export class RefactorEngine {
             let modified = originalContent;
             let count = 0;
             if (type === 'page-object') {
-                // Replace `class OldName` -> `class NewName`
-                const classReg = new RegExp(`\\bclass\\s+${oldName}\\b`, 'g');
-                const classMatches = (modified.match(classReg) || []).length;
-                if (classMatches > 0) {
-                    modified = modified.replace(classReg, `class ${newName}`);
-                    count += classMatches;
+                // Nested page objects are referenced as `Page.<Namespace>.<name>`; flat ones as `Page.<name>` too.
+                const pageRefReg = new RegExp(`\\bPage\\.${oldSegments.join('\\.')}\\b`, 'g');
+                const pageRefMatches = (modified.match(pageRefReg) || []).length;
+                if (pageRefMatches > 0) {
+                    modified = modified.replace(pageRefReg, `Page.${newSegments.join('.')}`);
+                    count += pageRefMatches;
                 }
-                // Replace `new OldName` -> `new NewName` (e.g. `export default new OldName()`, `new OldName(...)`)
-                const newReg = new RegExp(`\\bnew\\s+${oldName}\\b`, 'g');
-                const newMatches = (modified.match(newReg) || []).length;
-                if (newMatches > 0) {
-                    modified = modified.replace(newReg, `new ${newName}`);
-                    count += newMatches;
-                }
-                // Replace `export default OldName` -> `export default NewName`
-                const exportDefaultReg = new RegExp(`\\bexport\\s+default\\s+${oldName}\\b`, 'g');
-                const exportDefaultMatches = (modified.match(exportDefaultReg) || []).length;
-                if (exportDefaultMatches > 0) {
-                    modified = modified.replace(exportDefaultReg, `export default ${newName}`);
-                    count += exportDefaultMatches;
+                // A nested page object's class lives in its own folder, so only that folder's files are rewritten for it.
+                const declaredHere = !isNestedPageObject || filePath.startsWith(poSourceDir + path.sep);
+                if (declaredHere) {
+                    // Replace `class OldName` -> `class NewName`
+                    const classReg = new RegExp(`\\bclass\\s+${oldLeaf}\\b`, 'g');
+                    const classMatches = (modified.match(classReg) || []).length;
+                    if (classMatches > 0) {
+                        modified = modified.replace(classReg, `class ${newLeaf}`);
+                        count += classMatches;
+                    }
+                    // Replace `new OldName` -> `new NewName` (e.g. `export default new OldName()`, `new OldName(...)`)
+                    const newReg = new RegExp(`\\bnew\\s+${oldLeaf}\\b`, 'g');
+                    const newMatches = (modified.match(newReg) || []).length;
+                    if (newMatches > 0) {
+                        modified = modified.replace(newReg, `new ${newLeaf}`);
+                        count += newMatches;
+                    }
+                    // Replace `export default OldName` -> `export default NewName`
+                    const exportDefaultReg = new RegExp(`\\bexport\\s+default\\s+${oldLeaf}\\b`, 'g');
+                    const exportDefaultMatches = (modified.match(exportDefaultReg) || []).length;
+                    if (exportDefaultMatches > 0) {
+                        modified = modified.replace(exportDefaultReg, `export default ${newLeaf}`);
+                        count += exportDefaultMatches;
+                    }
                 }
-                // Replace `OldName.` -> `NewName.`
-                const refReg = new RegExp(`\\b${oldName}\\.`, 'g');
-                const refMatches = (modified.match(refReg) || []).length;
-                if (refMatches > 0) {
-                    modified = modified.replace(refReg, `${newName}.`);
-                    count += refMatches;
+                // Replace `OldName.` -> `NewName.` (flat page objects only: a bare nested leaf name is too generic to match)
+                if (!isNestedPageObject) {
+                    const refReg = new RegExp(`\\b${oldName}\\.`, 'g');
+                    const refMatches = (modified.match(refReg) || []).length;
+                    if (refMatches > 0) {
+                        modified = modified.replace(refReg, `${newName}.`);
+                        count += refMatches;
+                    }
                 }
             }
             else if (type === 'step') {
@@ -416,7 +444,7 @@ export class RefactorEngine {
         // Target Collision Guards (Priority 2 - checked only if source entity exists and skipPathRename is false)
         if (!skipPathRename) {
             if (type === 'page-object') {
-                const targetPoDir = path.join(workspaceRoot, 'page-objects', targetNewName);
+                const targetPoDir = path.join(workspaceRoot, 'page-objects', ...newSegments);
                 if (fs.existsSync(targetPoDir)) {
                     return {
                         status: 'failed',

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

@@ -0,0 +1,10 @@
+import type { DevServerHealthCheck } from '../config/schema.js';
+/**
+ * Rejects a `healthCheck` entry that cannot be evaluated, before any request is sent.
+ */
+export declare function validateHealthCheck(serverName: string, check: DevServerHealthCheck): void;
+/**
+ * Requests `url + check.path` and reports the first mismatch against the expected status and body text.
+ * Resolves to `null` when the response matches, otherwise to a human-readable failure reason.
+ */
+export declare function checkDevServerHealth(url: string, check: DevServerHealthCheck): Promise<string | null>;

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

@@ -0,0 +1,65 @@
+import http from 'node:http';
+import https from 'node:https';
+const HEALTH_CHECK_TIMEOUT_MS = 5000;
+/**
+ * Rejects a `healthCheck` entry that cannot be evaluated, before any request is sent.
+ */
+export function validateHealthCheck(serverName, check) {
+    if (typeof check.path !== 'string' || check.path.trim() === '') {
+        throw new Error(`Dev server "${serverName}" healthCheck.path must be a non-empty string.`);
+    }
+    if (check.status !== undefined && (!Number.isInteger(check.status) || check.status < 100 || check.status > 599)) {
+        throw new Error(`Dev server "${serverName}" healthCheck.status must be an HTTP status code (100-599).`);
+    }
+    if (check.bodyIncludes !== undefined && typeof check.bodyIncludes !== 'string') {
+        throw new Error(`Dev server "${serverName}" healthCheck.bodyIncludes must be a string.`);
+    }
+}
+/**
+ * Requests `url + check.path` and reports the first mismatch against the expected status and body text.
+ * Resolves to `null` when the response matches, otherwise to a human-readable failure reason.
+ */
+export async function checkDevServerHealth(url, check) {
+    const requestPath = check.path.startsWith('/') ? check.path : `/${check.path}`;
+    const label = `GET ${requestPath}`;
+    const expectedStatus = check.status ?? 200;
+    let target;
+    try {
+        target = new URL(`${url.replace(/\/+$/, '')}${requestPath}`);
+    }
+    catch {
+        return `${label} could not be sent because "${url}" is not a valid URL`;
+    }
+    const transport = target.protocol === 'https:' ? https : http;
+    return new Promise((resolve) => {
+        const req = transport.request(target, { method: 'GET', timeout: HEALTH_CHECK_TIMEOUT_MS, rejectUnauthorized: false }, (res) => {
+            const status = res.statusCode ?? 0;
+            if (status !== expectedStatus) {
+                res.resume();
+                resolve(`${label} returned ${status} (expected ${expectedStatus})`);
+                return;
+            }
+            if (check.bodyIncludes === undefined) {
+                res.resume();
+                resolve(null);
+                return;
+            }
+            const expectedText = check.bodyIncludes;
+            let body = '';
+            res.setEncoding('utf-8');
+            res.on('data', (chunk) => {
+                body += chunk;
+            });
+            res.on('end', () => {
+                resolve(body.includes(expectedText) ? null : `${label} response body does not include "${expectedText}"`);
+            });
+            res.on('error', (err) => resolve(`${label} failed: ${err.message}`));
+        });
+        req.on('timeout', () => {
+            req.destroy();
+            resolve(`${label} timed out after ${HEALTH_CHECK_TIMEOUT_MS}ms`);
+        });
+        req.on('error', (err) => resolve(`${label} failed: ${err.message}`));
+        req.end();
+    });
+}

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

@@ -27,6 +27,11 @@ export declare class DevServerManager {
      * reuses the instance. Otherwise, spawns the process and polls until ready.
      */
     ensureServer(config: DevServerConfig, rootCwd?: string): Promise<RunningDevServer>;
+    /**
+     * Verifies the `healthCheck` request when configured. Throws when the response does not match,
+     * which means the URL is answered by something other than this project's dev server.
+     */
+    private assertHealthy;
     /**
      * Starts all matching dev servers in parallel.
      */

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

@@ -3,6 +3,7 @@ import http from 'node:http';
 import https from 'node:https';
 import path from 'node:path';
 import spawn from 'cross-spawn';
+import { checkDevServerHealth, validateHealthCheck } from './dev-server-health.js';
 export class DevServerManager {
     spawnedProcesses = new Map();
     cleanupRegistered = false;
@@ -113,10 +114,14 @@ export class DevServerManager {
         const serverName = config.name || config.url;
         const timeoutMs = config.timeout ?? 60000;
         const reuse = config.reuseExistingServer !== false;
+        if (config.healthCheck)
+            validateHealthCheck(serverName, config.healthCheck);
         // Check if server is already running
         if (reuse) {
             const isRunning = await DevServerManager.probeUrl(config.url, 1000);
             if (isRunning) {
+                // A reused server is not ours: fail the run rather than spawn or report it as ready.
+                await this.assertHealthy(config, serverName);
                 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,
@@ -163,6 +168,14 @@ export class DevServerManager {
             }
             isReady = await DevServerManager.probeUrl(config.url, 500);
             if (isReady) {
+                try {
+                    await this.assertHealthy(config, serverName);
+                }
+                catch (error) {
+                    this.killProcess(child);
+                    this.spawnedProcesses.delete(serverName);
+                    throw error;
+                }
                 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 {
@@ -181,6 +194,18 @@ export class DevServerManager {
         throw new Error(`Dev server "${serverName}" timed out after ${timeoutMs}ms waiting for ${config.url}.\n` +
             `Last output:\n${errorLogs || '(no output)'}`);
     }
+    /**
+     * Verifies the `healthCheck` request when configured. Throws when the response does not match,
+     * which means the URL is answered by something other than this project's dev server.
+     */
+    async assertHealthy(config, serverName) {
+        if (!config.healthCheck)
+            return;
+        const failure = await checkDevServerHealth(config.url, config.healthCheck);
+        if (failure) {
+            throw new Error(`Dev server "${serverName}" at ${config.url} failed its health check: ${failure} — another server may be using the port`);
+        }
+    }
     /**
      * Starts all matching dev servers in parallel.
      */

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

@@ -1,2 +1,19 @@
 export declare function checkUpdateInBackground(): void;
+/**
+ * Reads the version of `pkgName` as actually resolved by the running CLI. The CLI's own package is
+ * found by walking up from this module (never from the workspace root or cwd); other packages are
+ * resolved from this module's location. Returns null when the package cannot be read.
+ */
+export declare function readInstalledVersion(pkgName: string): string | null;
+interface CachedUpdate {
+    pkg: string;
+    latest?: string;
+}
+/** First cached package whose installed version differs from its latest version. */
+export declare function findAvailableUpdate(candidates: CachedUpdate[], resolveInstalled?: (pkgName: string) => string | null): {
+    pkg: string;
+    current: string;
+    latest: string;
+} | null;
 export declare function displayUpdateNotificationIfNeeded(): void;
+export {};