@testspectra/cli 1.1.8-rc.24 → 1.1.8-rc.28

package/README.md

@@ -44,31 +44,34 @@ portable JS, so one npm package can't ship a single binary that works on every O
 `@testspectra/cli` follows the same pattern as esbuild/swc/turbo:
 
 - `@testspectra/cli` itself ships **no native binary** — only the JS launcher (`bin/spectra.js`).
-- The binary is published as four separate, platform-locked packages under `cli/npm/`:
+- The binary is published as three separate, platform-locked packages under `cli/npm/`:
   - `@testspectra/cli-darwin-arm64`
   - `@testspectra/cli-win32-x64`
-  - `@testspectra/cli-win32-arm64`
   - `@testspectra/cli-linux-x64`
 
+  (Windows arm64 has no native build — `resolveBinaryPath()` throws a clear "not supported"
+  error there instead of pointing at a package that was never published.)
+
   Each has `os`/`cpu` fields in its `package.json`, so npm/pnpm/yarn only ever download the one
   matching the installing machine.
-- `@testspectra/cli` lists all four as `optionalDependencies`, pinned to an exact version (not
+
+- `@testspectra/cli` lists all three as `optionalDependencies`, pinned to an exact version (not
   `^`) that always matches the `@testspectra/cli` release it ships with.
 - At runtime, `RustCoreBridge.resolveBinaryPath()` (`cli/src/runner/bridge.ts`) resolves the
   binary from whichever platform package got installed (`require.resolve('@testspectra/cli-<platform>/package.json')`),
   falling back to the monorepo's local build output (`core/target/release/...`) for local dev
   where no optional package is installed.
-- If a user's platform/arch isn't one of the four above, install succeeds (optional deps just
+- If a user's platform/arch isn't one of the three above, install succeeds (optional deps just
   get skipped) but `resolveBinaryPath()` throws a clear "not supported" error at run time.
 
 ### Building & releasing all platforms
 
-`scripts/build-cross-platform-binaries.js` builds the binary for all four platforms from a
+`scripts/build-cross-platform-binaries.js` builds the binary for all three platforms from a
 single macOS machine and copies each into `cli/npm/<platform>/bin/`:
 
 - **macOS arm64** — native `cargo build` (this machine only builds arm64; there's no x64 macOS
   package).
-- **Windows x64 / arm64** — cross-compiled via [`cargo-xwin`](https://github.com/rust-cross/cargo-xwin)
+- **Windows x64** — cross-compiled via [`cargo-xwin`](https://github.com/rust-cross/cargo-xwin)
   (`cargo install cargo-xwin`), which downloads the MSVC CRT/Windows SDK bits needed for linking.
   reqwest's default `native-tls` backend uses Schannel on Windows, so no OpenSSL cross-compile
   headaches here.
@@ -79,8 +82,8 @@ single macOS machine and copies each into `cli/npm/<platform>/bin/`:
   Docker must be running for this step.
 
 `scripts/release-cli-local.sh` runs this automatically, then stamps every `cli/npm/*/package.json`
-and `cli/package.json`'s `optionalDependencies` with the target version, packs all five tarballs,
-and (with `--publish`) publishes the four platform packages before `@testspectra/cli` itself.
+and `cli/package.json`'s `optionalDependencies` with the target version, packs all four tarballs,
+and (with `--publish`) publishes the three platform packages before `@testspectra/cli` itself.
 
 ---
 

package/bin/.testspectra-runner.hash

@@ -0,0 +1 @@
+2db95c618fc201b3c5e4b2f56e93c5e5fca36ba0d31250c65c98aabed5385361

package/dist/commands/__tests__/doctor-filter.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect, vi } from 'vitest';
+const { execFileSyncMock } = vi.hoisted(() => ({ execFileSyncMock: vi.fn() }));
+vi.mock('child_process', () => ({
+    execFileSync: execFileSyncMock,
+    spawn: vi.fn(),
+}));
+vi.mock('../../runner/bridge.js', () => ({
+    RustCoreBridge: { resolveBinaryPath: () => '/fake/testspectra-runner' },
+}));
+import { runSystemChecks } from '../doctor.js';
+const EMPTY = JSON.stringify({ all_ready: true, missing_count: 0, dependencies: [] });
+describe('runSystemChecks filter forwarding', () => {
+    it('forwards a category scope to the runner', async () => {
+        execFileSyncMock.mockReturnValueOnce(EMPTY);
+        await runSystemChecks('/tmp/ws', { scope: 'web' });
+        const [, args] = execFileSyncMock.mock.calls.at(-1);
+        expect(args).toEqual(['doctor', '--json', '--scope', 'web']);
+    });
+    it('forwards a fine-grained --only filter (single dependency)', async () => {
+        execFileSyncMock.mockReturnValueOnce(EMPTY);
+        await runSystemChecks('/tmp/ws', { only: 'chrome' });
+        const [, args] = execFileSyncMock.mock.calls.at(-1);
+        expect(args).toEqual(['doctor', '--json', '--only', 'chrome']);
+    });
+    it('forwards both scope and only when provided', async () => {
+        execFileSyncMock.mockReturnValueOnce(EMPTY);
+        await runSystemChecks('/tmp/ws', { scope: 'web', only: 'chrome,adb' });
+        const [, args] = execFileSyncMock.mock.calls.at(-1);
+        expect(args).toEqual(['doctor', '--json', '--scope', 'web', '--only', 'chrome,adb']);
+    });
+    it('omits filters entirely when none are requested (full doctor)', async () => {
+        execFileSyncMock.mockReturnValueOnce(EMPTY);
+        await runSystemChecks('/tmp/ws');
+        const [, args] = execFileSyncMock.mock.calls.at(-1);
+        expect(args).toEqual(['doctor', '--json']);
+    });
+});

package/dist/commands/__tests__/doctor-scope.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/__tests__/doctor-scope.test.js

@@ -0,0 +1,24 @@
+import { describe, it, expect, vi } from 'vitest';
+const { execFileSyncMock } = vi.hoisted(() => ({ execFileSyncMock: vi.fn() }));
+vi.mock('child_process', () => ({
+    execFileSync: execFileSyncMock,
+    spawn: vi.fn(),
+}));
+vi.mock('../../runner/bridge.js', () => ({
+    RustCoreBridge: { resolveBinaryPath: () => '/fake/testspectra-runner' },
+}));
+import { runSystemChecks } from '../doctor.js';
+describe('runSystemChecks scope forwarding', () => {
+    it('forwards a category scope to the runner (efficient partial doctor)', async () => {
+        execFileSyncMock.mockReturnValueOnce(JSON.stringify({ all_ready: true, missing_count: 0, dependencies: [] }));
+        await runSystemChecks('/tmp/ws', 'web');
+        const [, args] = execFileSyncMock.mock.calls.at(-1);
+        expect(args).toEqual(['doctor', '--json', '--scope', 'web']);
+    });
+    it('omits --scope entirely when no scope is requested (full doctor)', async () => {
+        execFileSyncMock.mockReturnValueOnce(JSON.stringify({ all_ready: true, missing_count: 0, dependencies: [] }));
+        await runSystemChecks('/tmp/ws');
+        const [, args] = execFileSyncMock.mock.calls.at(-1);
+        expect(args).toEqual(['doctor', '--json']);
+    });
+});

package/dist/commands/__tests__/test-error-streaming.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/__tests__/test-error-streaming.test.js

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { isVitestNoise, sanitizeErrorMessage } from '@testspectra/react';
+import { Reporter } from '../../runner/reporter.js';
+describe('spectra test error streaming and formatting', () => {
+    it('sanitizes Vitest/Vite error messages without leaking behind-the-scenes tooling', () => {
+        const rawError = 'Failed to fetch dynamically imported module: http://localhost:63315/@fs/D:/wangs-ui-react/packages/testing-library/page-objects/AccordionComponent/web.ts?import';
+        const sanitized = sanitizeErrorMessage(rawError);
+        expect(sanitized).toBe('Failed to load module: D:/wangs-ui-react/packages/testing-library/page-objects/AccordionComponent/web.ts');
+        expect(sanitized).not.toContain('localhost');
+        expect(sanitized).not.toContain('@fs');
+        expect(sanitized).not.toContain('?import');
+    });
+    it('filters Vitest CLI runner noise while allowing actual errors through', () => {
+        expect(isVitestNoise('RUN  v2.1.8 /Volumes/Home/TestSpectra')).toBe(true);
+        expect(isVitestNoise('Test Files  1 failed (1)')).toBe(true);
+        expect(isVitestNoise('⎯⎯⎯⎯⎯⎯⎯ Failed Suites 1 ⎯⎯⎯⎯⎯⎯⎯')).toBe(true);
+        expect(isVitestNoise('Re-optimizing dependencies because vite config has changed')).toBe(true);
+        expect(isVitestNoise('Error: Cannot find module "./Button"')).toBe(false);
+        expect(isVitestNoise('SyntaxError: Unexpected token (10:15)')).toBe(false);
+    });
+    it('formats multi-line errors with clean indentation in Reporter', () => {
+        const reporter = new Reporter();
+        reporter.addLog({
+            timestamp: '12:00:00',
+            level: 'INFO',
+            message: '[TESTSPECTRA_TEST_START] {"title":"specs/Accordion/TC-0009/web.test.tsx"}',
+        });
+        reporter.addLog({
+            timestamp: '12:00:00',
+            level: 'INFO',
+            message: '[TESTSPECTRA_TEST_ERROR] Failed to load module: D:/wangs-ui-react/page-objects/Accordion/web.ts',
+        });
+        reporter.addLog({
+            timestamp: '12:00:00',
+            level: 'INFO',
+            message: '[TESTSPECTRA_TEST_FAIL] specs/Accordion/TC-0009/web.test.tsx (0ms)',
+        });
+        const result = reporter.generateResult('failed', '0.1s');
+        expect(result.failedCount).toBe(1);
+        expect(result.passedCount).toBe(0);
+        expect(result.status).toBe('failed');
+    });
+    it('guarantees failedCount is at least 1 when test run fails without test events', () => {
+        const reporter = new Reporter();
+        const ok = false;
+        const result = reporter.generateResult(ok ? 'passed' : 'failed', '0.1s');
+        const failedCount = !ok && result.failedCount === 0 ? 1 : result.failedCount;
+        const totalTests = result.passedCount + failedCount;
+        expect(failedCount).toBe(1);
+        expect(totalTests).toBe(1);
+    });
+});

package/dist/commands/__tests__/test-scaffolding.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/__tests__/test-scaffolding.test.js

@@ -0,0 +1,32 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { ensureTestSpectraScaffolding } from '../test.js';
+describe('spectra test pre-flight scaffolding (docs/v2/features/component-testing/react/README.md)', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'testspectra-test-scaffold-'));
+    });
+    afterEach(() => {
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch { }
+    });
+    it('generates the .testspectra solution tsconfig when it is missing (clean clone / CI)', () => {
+        const masterConfig = path.join(tmpDir, '.testspectra', 'tsconfig.json');
+        expect(fs.existsSync(masterConfig)).toBe(false);
+        ensureTestSpectraScaffolding(tmpDir);
+        // The exact file `vite:esbuild` tries to read via the root tsconfig's `references` entry.
+        expect(fs.existsSync(masterConfig)).toBe(true);
+        expect(fs.existsSync(path.join(tmpDir, '.testspectra', 'tsconfig', 'web.json'))).toBe(true);
+    });
+    it('leaves an existing scaffolding untouched', () => {
+        const masterConfig = path.join(tmpDir, '.testspectra', 'tsconfig.json');
+        fs.mkdirSync(path.dirname(masterConfig), { recursive: true });
+        fs.writeFileSync(masterConfig, '{"custom":true}\n', 'utf-8');
+        ensureTestSpectraScaffolding(tmpDir);
+        expect(fs.readFileSync(masterConfig, 'utf-8')).toBe('{"custom":true}\n');
+    });
+});

package/dist/commands/__tests__/upgrade.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/__tests__/upgrade.test.js

@@ -0,0 +1,95 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { execFileSync, execSync } from 'child_process';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { upgradeCommand } from '../upgrade.js';
+const DOCTOR_JSON = JSON.stringify({
+    all_ready: true,
+    missing_count: 0,
+    dependencies: [
+        {
+            name: 'Google Chrome',
+            category: 'web',
+            installed: true,
+            version: 'Google Chrome 123.0.0.0 (Chrome for Testing)',
+            required: true,
+            required_version: 'Stable / CfT',
+            depends_on: [],
+        },
+        {
+            name: 'Bun',
+            category: 'core',
+            installed: true,
+            version: 'v1.0.0',
+            required: true,
+            required_version: '>=1.0.0',
+            depends_on: [],
+        },
+    ],
+});
+vi.mock('child_process', () => ({
+    execFileSync: vi.fn((_cmd, args) => Array.isArray(args) && args[0] === 'doctor' ? DOCTOR_JSON : '"9.9.9"'),
+    execSync: vi.fn(),
+}));
+describe('upgradeCommand self-upgrade mechanism (docs/v2/features/upgrade-mechanism-and-notifications.md)', () => {
+    let tmpDir;
+    const originalCwd = process.cwd();
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'testspectra-upgrade-test-'));
+        process.chdir(tmpDir);
+        vi.clearAllMocks();
+        vi.stubGlobal('fetch', vi.fn(async (url) => {
+            const href = String(url);
+            if (href.includes('chrome-for-testing')) {
+                return { ok: true, json: async () => ({ channels: { Stable: { version: '999.0.0.0' } } }) };
+            }
+            if (href.includes('github')) {
+                return { ok: true, json: async () => ({ tag_name: 'bun-v2.0.0' }) };
+            }
+            return {
+                ok: true,
+                text: async () => '<remotePackage path="platform-tools"><revision><major>99</major><minor>0</minor><micro>0</micro></revision></remotePackage>',
+            };
+        }));
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        process.chdir(originalCwd);
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch { }
+    });
+    it('emits a pure JSON payload covering packages and drivers in --json mode', async () => {
+        const logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        await upgradeCommand([], { json: true });
+        expect(logSpy).toHaveBeenCalledTimes(1);
+        const payload = JSON.parse(logSpy.mock.calls[0][0]);
+        expect(payload.packages).toHaveLength(3);
+        expect(payload.packages.every((p) => p.latest === '9.9.9')).toBe(true);
+        expect(payload.drivers).toHaveLength(2);
+        expect(payload.drivers.find((d) => d.name === 'Google Chrome')?.latest).toBe('999.0.0.0');
+        expect(payload.updatesAvailable).toBeGreaterThan(0);
+        expect(execSync).not.toHaveBeenCalled();
+        logSpy.mockRestore();
+    });
+    it('restricts to a single package (no drivers) when package names are passed', async () => {
+        const logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        await upgradeCommand(['@testspectra/cli'], { json: true });
+        const payload = JSON.parse(logSpy.mock.calls[0][0]);
+        expect(payload.packages).toHaveLength(1);
+        expect(payload.packages[0].pkg).toBe('@testspectra/cli');
+        expect(payload.drivers).toHaveLength(0);
+        logSpy.mockRestore();
+    });
+    it('reports available updates in --check mode without running the package manager', async () => {
+        const logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        await upgradeCommand([], { check: true });
+        expect(execFileSync).toHaveBeenCalled();
+        expect(execSync).not.toHaveBeenCalled();
+        const output = logSpy.mock.calls.map((c) => String(c[0])).join('\n');
+        expect(output).toContain('package update(s) available');
+        logSpy.mockRestore();
+    });
+});

package/dist/commands/add.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'url';
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
 import { TypeGenerator } from '../types/generator.js';
+import { ConfigLoader } from '../config/loader.js';
 function parsePnpmWorkspaceGlobs(content) {
     const lines = content.split('\n');
     const globs = [];
@@ -107,9 +108,8 @@ export async function addCommand(moduleNameArg, options = {}) {
     let rootDir = cwd;
     let cur = cwd;
     while (cur !== path.dirname(cur)) {
-        if (fs.existsSync(path.join(cur, 'spectra.config.ts')) ||
-            fs.existsSync(path.join(cur, 'pnpm-workspace.yaml')) ||
-            fs.existsSync(path.join(cur, 'nx.json'))) {
+        const hasConfig = ConfigLoader.CONFIG_FILE_NAMES.some((name) => fs.existsSync(path.join(cur, name)));
+        if (hasConfig || fs.existsSync(path.join(cur, 'pnpm-workspace.yaml')) || fs.existsSync(path.join(cur, 'nx.json'))) {
             rootDir = cur;
             break;
         }

package/dist/commands/doctor.d.ts

@@ -13,9 +13,17 @@ export interface SystemCheckResult {
     missing_count: number;
     dependencies: DependencyStatus[];
 }
-export declare function runSystemChecks(cwd?: string): Promise<SystemCheckResult>;
+export interface SystemCheckOptions {
+    /** Category filter: `core`, `web`, or `mobile` (default: all). */
+    scope?: string;
+    /** Comma-separated specific dependency keys, e.g. `chrome` or `chrome,adb` (takes precedence over `scope`). */
+    only?: string;
+}
+export declare function runSystemChecks(cwd?: string, options?: SystemCheckOptions): Promise<SystemCheckResult>;
 export declare function doctorCommand(options?: {
     fix?: boolean;
     json?: boolean;
     verbose?: boolean;
+    scope?: string;
+    only?: string;
 }): Promise<void>;

package/dist/commands/doctor.js

@@ -9,9 +9,16 @@ function getRunnerEnv() {
         TEST_SPECTRA_DRIVER_CACHE: globalDriversDir,
     };
 }
-export async function runSystemChecks(cwd = process.cwd()) {
+export async function runSystemChecks(cwd = process.cwd(), options = {}) {
     const binPath = RustCoreBridge.resolveBinaryPath();
-    const stdout = execFileSync(binPath, ['doctor', '--json'], {
+    const args = ['doctor', '--json'];
+    if (options.scope) {
+        args.push('--scope', options.scope);
+    }
+    if (options.only) {
+        args.push('--only', options.only);
+    }
+    const stdout = execFileSync(binPath, args, {
         cwd,
         env: getRunnerEnv(),
         encoding: 'utf8',
@@ -29,11 +36,17 @@ export async function doctorCommand(options = {}) {
     if (options.verbose) {
         args.push('--verbose');
     }
+    if (options.scope) {
+        args.push('--scope', options.scope);
+    }
+    if (options.only) {
+        args.push('--only', options.only);
+    }
     if (options.fix) {
         args.push('--fix');
     }
     if (options.json) {
-        const result = await runSystemChecks(cwd);
+        const result = await runSystemChecks(cwd, { scope: options.scope, only: options.only });
         console.log(JSON.stringify(result, null, 2));
         return;
     }

package/dist/commands/install.js

@@ -17,6 +17,9 @@ export async function installCommand(item, options = {}) {
     if (item) {
         args.push(item);
     }
+    if (options.force) {
+        args.push('--force');
+    }
     return new Promise((resolve) => {
         let child;
         if (binPath === 'cargo') {

package/dist/commands/test.d.ts

@@ -1,5 +1,6 @@
 export interface TestCommandOptions {
     cwd?: string;
+    runner?: 'spectra' | 'vitest';
     headed?: boolean;
     headless?: boolean;
     stepDelay?: string | number;
@@ -8,6 +9,18 @@ export interface TestCommandOptions {
     output?: string;
     concurrency?: string | number;
 }
+/**
+ * Guarantees the `.testspectra` solution-tsconfig scaffolding exists before Vitest starts.
+ *
+ * The bundled Vitest browser runner transpiles raw TypeScript specs/page-objects Just-In-Time.
+ * When it does, `vite:esbuild` walks the nearest `tsconfig.json` and tries to read every entry in
+ * its `references` — including `./.testspectra/tsconfig.json`. That directory is gitignored, so on
+ * a clean clone / fresh CI checkout the reference points at a file that does not exist, esbuild
+ * throws `ENOENT`, Vite answers HTTP 500, and every suite dies with "Failed to fetch dynamically
+ * imported module" before a single assertion runs. Regenerating the scaffolding up front (same
+ * output as `spectra sync-types`) keeps the reference resolvable.
+ */
+export declare function ensureTestSpectraScaffolding(cwd: string): void;
 /**
  * `spectra test` — delegates to `@testspectra/react`'s bundled Vitest browser-mode runner for
  * component testing. Deliberately separate from `spectra run` (E2E via core/orchestrator): see

package/dist/commands/test.js

@@ -1,9 +1,30 @@
+import fs from 'node:fs';
 import path from 'node:path';
 import chalk from 'chalk';
 import * as p from '@clack/prompts';
+import { ConfigLoader } from '../config/loader.js';
 import { renderSummaryView } from '../reporter/summary-view.js';
 import { Reporter } from '../runner/reporter.js';
+import { RustCoreBridge } from '../runner/bridge.js';
+import { TypeGenerator } from '../generator/type-generator.js';
 import { runSystemChecks } from './doctor.js';
+/**
+ * Guarantees the `.testspectra` solution-tsconfig scaffolding exists before Vitest starts.
+ *
+ * The bundled Vitest browser runner transpiles raw TypeScript specs/page-objects Just-In-Time.
+ * When it does, `vite:esbuild` walks the nearest `tsconfig.json` and tries to read every entry in
+ * its `references` — including `./.testspectra/tsconfig.json`. That directory is gitignored, so on
+ * a clean clone / fresh CI checkout the reference points at a file that does not exist, esbuild
+ * throws `ENOENT`, Vite answers HTTP 500, and every suite dies with "Failed to fetch dynamically
+ * imported module" before a single assertion runs. Regenerating the scaffolding up front (same
+ * output as `spectra sync-types`) keeps the reference resolvable.
+ */
+export function ensureTestSpectraScaffolding(cwd) {
+    const masterConfigPath = path.join(cwd, '.testspectra', 'tsconfig.json');
+    if (fs.existsSync(masterConfigPath))
+        return;
+    TypeGenerator.generateAll(cwd);
+}
 /**
  * Finds the Chrome-for-Testing binary that `spectra doctor` already installs/manages for the
  * E2E CDP driver (`core/driver-cdp`) — same install, same binary. `@testspectra/react` must not
@@ -14,7 +35,9 @@ import { runSystemChecks } from './doctor.js';
  */
 async function resolveBrowserExecutable(cwd) {
     try {
-        const { dependencies } = await runSystemChecks(cwd);
+        // `--only chrome` runs exactly one check — no adb/bun/git spawns, no Matchers lookup — since
+        // this call exists solely to locate the managed browser binary.
+        const { dependencies } = await runSystemChecks(cwd, { only: 'chrome' });
         const chrome = dependencies.find((d) => d.category === 'web' && d.name.includes('Chrome'));
         return chrome?.installed && chrome.location ? chrome.location : null;
     }
@@ -30,6 +53,11 @@ async function resolveBrowserExecutable(cwd) {
  */
 export async function testCommand(options = {}) {
     const cwd = options.cwd ?? process.cwd();
+    // User-facing phase log. Deliberately describes TestSpectra's own stages only — never the
+    // bundled runtime/toolchain underneath — so the CLI surface stays implementation-agnostic.
+    const logPhase = (message) => p.log.step(chalk.dim(message));
+    logPhase('Preparing component test workspace…');
+    ensureTestSpectraScaffolding(cwd);
     let reactPkg;
     try {
         reactPkg = await import('@testspectra/react');
@@ -41,6 +69,7 @@ export async function testCommand(options = {}) {
         process.exit(1);
         return;
     }
+    logPhase('Resolving managed test browser…');
     const browserExecutablePath = await resolveBrowserExecutable(cwd);
     if (!browserExecutablePath) {
         p.log.error(chalk.red('✖ TestSpectra-managed Chrome for Testing was not found.'));
@@ -64,6 +93,21 @@ export async function testCommand(options = {}) {
     else if (options.headless !== undefined) {
         headless = options.headless;
     }
+    // Fallback to spectra.config.ts if options were not explicitly provided on CLI
+    try {
+        const config = await ConfigLoader.loadConfig(cwd);
+        if (stepDelayMs === undefined && config?.webConfig?.stepDelay !== undefined) {
+            const parsed = parseInt(String(config.webConfig.stepDelay), 10);
+            if (!isNaN(parsed) && parsed >= 0)
+                stepDelayMs = parsed;
+        }
+        if (!options.headed && options.headless === undefined && config?.webConfig?.headless !== undefined) {
+            headless = String(config.webConfig.headless) !== 'false' && Boolean(config.webConfig.headless);
+        }
+    }
+    catch {
+        /* ignore config load failures */
+    }
     const concurrency = options.concurrency !== undefined ? parseInt(String(options.concurrency), 10) : undefined;
     const outputFile = options.output ? path.resolve(cwd, options.output) : undefined;
     // Reuses the exact same semantic terminal reporter `spectra run` drives (see
@@ -72,33 +116,81 @@ export async function testCommand(options = {}) {
     // / setup.ts), so the same Reporter class parses them with zero changes on either side.
     const reporter = new Reporter();
     const runStartedAt = Date.now();
-    const ok = await reactPkg.runComponentTests({
-        cwd,
-        headless,
-        stepDelayMs,
-        spec: options.spec,
-        outputFile,
-        concurrency: concurrency !== undefined && !isNaN(concurrency) ? concurrency : undefined,
-        browserExecutablePath,
-        onLine: (line) => {
-            // Strip ANSI and whitespace since Vitest might prefix or colorize console logs
-            const cleanLine = line.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, '').trim();
-            if (!cleanLine.startsWith('[TESTSPECTRA_'))
-                return;
-            reporter.addLog({ timestamp: new Date().toLocaleTimeString(), level: 'INFO', message: cleanLine });
-            if (!reporter.isInteractiveMode()) {
-                console.log(line);
-            }
-        },
-    });
+    let ok = false;
+    if (options.runner === 'vitest') {
+        logPhase('Starting component test runner (Vitest Browser Mode)…');
+        ok = await reactPkg.runComponentTests({
+            runner: 'vitest',
+            cwd,
+            headless,
+            stepDelayMs,
+            spec: options.spec,
+            outputFile,
+            concurrency: concurrency !== undefined && !isNaN(concurrency) ? concurrency : undefined,
+            browserExecutablePath,
+            onLine: (line) => {
+                const cleanLine = line.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, '').trim();
+                if (!cleanLine)
+                    return;
+                if (cleanLine.startsWith('[TESTSPECTRA_')) {
+                    reporter.addLog({ timestamp: new Date().toLocaleTimeString(), level: 'INFO', message: cleanLine });
+                    if (!reporter.isInteractiveMode()) {
+                        console.log(cleanLine);
+                    }
+                    return;
+                }
+                if (reactPkg.isVitestNoise?.(cleanLine)) {
+                    return;
+                }
+                const sanitized = reactPkg.sanitizeErrorMessage?.(cleanLine) ?? cleanLine;
+                reporter.addLog({ timestamp: new Date().toLocaleTimeString(), level: 'ERROR', message: sanitized });
+                if (!reporter.isInteractiveMode()) {
+                    console.error(chalk.red(sanitized));
+                }
+            },
+        });
+    }
+    else {
+        logPhase('Starting component test runner (Spectra Native CDP Engine)…');
+        const bundleServer = await reactPkg.startBundleServer({
+            testRoot: cwd,
+            stepDelayMs: stepDelayMs ?? 0,
+        });
+        try {
+            const home = process.env.HOME || process.env.USERPROFILE || '';
+            const globalAppDataPath = path.join(home, '.testspectra');
+            const appDataPath = globalAppDataPath;
+            const runResult = await RustCoreBridge.run({
+                baseDir: cwd,
+                appDataPath,
+                platform: 'component',
+                config: {
+                    bundleServerUrl: bundleServer.url,
+                    webConfig: {
+                        headless,
+                        stepDelay: stepDelayMs,
+                        browserExecutablePath,
+                    },
+                },
+                specs: options.spec ? [options.spec] : undefined,
+                concurrency: concurrency !== undefined && !isNaN(concurrency) ? concurrency : undefined,
+                outputJsonPath: outputFile,
+            }, reporter);
+            ok = runResult.status.toLowerCase() === 'passed';
+        }
+        finally {
+            bundleServer.stop();
+        }
+    }
     const durationMs = Date.now() - runStartedAt;
     const result = reporter.generateResult(ok ? 'passed' : 'failed', `${(durationMs / 1000).toFixed(1)}s`);
-    const totalTests = result.passedCount + result.failedCount;
+    const failedCount = !ok && result.failedCount === 0 ? 1 : result.failedCount;
+    const totalTests = result.passedCount + failedCount;
     renderSummaryView({
         totalSuites: totalTests,
         totalTests,
         passedCount: result.passedCount,
-        failedCount: result.failedCount,
+        failedCount,
         durationMs,
         reportLocation: outputFile ? path.relative(cwd, outputFile) : '(use -o/--output to save a report)',
     });

package/dist/commands/upgrade.d.ts

@@ -1,5 +1,12 @@
-export declare function upgradeCommand(options?: {
+export interface PackageUpdate {
+    pkg: string;
+    current: string | null;
+    latest: string | null;
+    needsUpdate: boolean;
+}
+export declare function upgradeCommand(requestedPackages?: string[], options?: {
     check?: boolean;
     packagesOnly?: boolean;
     driversOnly?: boolean;
+    json?: boolean;
 }): Promise<void>;