@testspectra/cli 1.1.0-rc.0 → 1.1.0-rc.1

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

@@ -6,19 +6,17 @@ import { TypeGenerator } from '../../types/generator.js';
 describe('runCommand Integration & Dynamic Worker Sizing', () => {
     it('passes calculated dynamic worker count to RustCoreBridge payload', async () => {
         vi.spyOn(TypeGenerator, 'writeDeclarationFiles').mockImplementation(() => { });
+        vi.spyOn(TypeGenerator, 'syncEnvDeclaration').mockResolvedValue(undefined);
         vi.spyOn(ConfigLoader, 'loadConfig').mockResolvedValue({
             webConfig: {
                 baseUrl: 'http://localhost:3000',
                 maxConcurrentSessions: '1',
                 headless: true,
                 implicitWait: '5000',
-                pageLoadTimeout: '30000',
-                scriptTimeout: '30000',
                 parallelizationMode: 'suite',
             },
             androidConfig: {},
             iosConfig: {},
-            browsers: [],
             executionConfig: {},
         });
         let bridgeOptionsReceived = null;
@@ -39,19 +37,17 @@ describe('runCommand Integration & Dynamic Worker Sizing', () => {
     });
     it('respects user-specified --concurrency option and passes it to RustCoreBridge', async () => {
         vi.spyOn(TypeGenerator, 'writeDeclarationFiles').mockImplementation(() => { });
+        vi.spyOn(TypeGenerator, 'syncEnvDeclaration').mockResolvedValue(undefined);
         vi.spyOn(ConfigLoader, 'loadConfig').mockResolvedValue({
             webConfig: {
                 baseUrl: 'http://localhost:3000',
                 maxConcurrentSessions: '1',
                 headless: true,
                 implicitWait: '5000',
-                pageLoadTimeout: '30000',
-                scriptTimeout: '30000',
                 parallelizationMode: 'suite',
             },
             androidConfig: {},
             iosConfig: {},
-            browsers: [],
             executionConfig: {},
         });
         let bridgeOptionsReceived = null;
@@ -71,6 +67,7 @@ describe('runCommand Integration & Dynamic Worker Sizing', () => {
     });
     it('correctly serializes target android and devices options into RustCoreBridge payload', async () => {
         vi.spyOn(TypeGenerator, 'writeDeclarationFiles').mockImplementation(() => { });
+        vi.spyOn(TypeGenerator, 'syncEnvDeclaration').mockResolvedValue(undefined);
         vi.spyOn(ConfigLoader, 'loadConfig').mockResolvedValue({
             webConfig: {
                 baseUrl: 'http://localhost:3000',
@@ -81,7 +78,6 @@ describe('runCommand Integration & Dynamic Worker Sizing', () => {
                 devices: [{ id: 'emulator-5554' }],
             },
             iosConfig: {},
-            browsers: [],
             executionConfig: {},
         });
         let bridgeOptionsReceived = null;
@@ -109,11 +105,11 @@ describe('runCommand Integration & Dynamic Worker Sizing', () => {
     });
     it('correctly serializes single --device option into devices array of objects', async () => {
         vi.spyOn(TypeGenerator, 'writeDeclarationFiles').mockImplementation(() => { });
+        vi.spyOn(TypeGenerator, 'syncEnvDeclaration').mockResolvedValue(undefined);
         vi.spyOn(ConfigLoader, 'loadConfig').mockResolvedValue({
             webConfig: { baseUrl: 'http://localhost:3000' },
             androidConfig: { driverServer: 'http://127.0.0.1:4800' },
             iosConfig: {},
-            browsers: [],
             executionConfig: {},
         });
         let bridgeOptionsReceived = null;
@@ -138,11 +134,11 @@ describe('runCommand Integration & Dynamic Worker Sizing', () => {
     });
     it('correctly serializes --all-devices flag into auto devices in config', async () => {
         vi.spyOn(TypeGenerator, 'writeDeclarationFiles').mockImplementation(() => { });
+        vi.spyOn(TypeGenerator, 'syncEnvDeclaration').mockResolvedValue(undefined);
         vi.spyOn(ConfigLoader, 'loadConfig').mockResolvedValue({
             webConfig: { baseUrl: 'http://localhost:3000' },
             androidConfig: { driverServer: 'http://127.0.0.1:4800' },
             iosConfig: {},
-            browsers: [],
             executionConfig: {},
         });
         let bridgeOptionsReceived = null;
@@ -167,11 +163,11 @@ describe('runCommand Integration & Dynamic Worker Sizing', () => {
     });
     it('correctly serializes --multi-device flag into auto devices in config', async () => {
         vi.spyOn(TypeGenerator, 'writeDeclarationFiles').mockImplementation(() => { });
+        vi.spyOn(TypeGenerator, 'syncEnvDeclaration').mockResolvedValue(undefined);
         vi.spyOn(ConfigLoader, 'loadConfig').mockResolvedValue({
             webConfig: { baseUrl: 'http://localhost:3000' },
             androidConfig: { driverServer: 'http://127.0.0.1:4800' },
             iosConfig: {},
-            browsers: [],
             executionConfig: {},
         });
         let bridgeOptionsReceived = null;
@@ -196,11 +192,11 @@ describe('runCommand Integration & Dynamic Worker Sizing', () => {
     });
     it('sets process.exitCode to 1 when tests fail', async () => {
         vi.spyOn(TypeGenerator, 'writeDeclarationFiles').mockImplementation(() => { });
+        vi.spyOn(TypeGenerator, 'syncEnvDeclaration').mockResolvedValue(undefined);
         vi.spyOn(ConfigLoader, 'loadConfig').mockResolvedValue({
             webConfig: { baseUrl: 'http://localhost:3000' },
             androidConfig: {},
             iosConfig: {},
-            browsers: [],
             executionConfig: {},
         });
         vi.spyOn(RustCoreBridge, 'run').mockImplementation(async () => {
@@ -220,11 +216,11 @@ describe('runCommand Integration & Dynamic Worker Sizing', () => {
     });
     it('incorporates TESTSPECTRA_CARRIED_OVER into summary card calculation', async () => {
         vi.spyOn(TypeGenerator, 'writeDeclarationFiles').mockImplementation(() => { });
+        vi.spyOn(TypeGenerator, 'syncEnvDeclaration').mockResolvedValue(undefined);
         vi.spyOn(ConfigLoader, 'loadConfig').mockResolvedValue({
             webConfig: { baseUrl: 'http://localhost:3000' },
             androidConfig: {},
             iosConfig: {},
-            browsers: [],
             executionConfig: {},
         });
         vi.spyOn(RustCoreBridge, 'run').mockImplementation(async () => {
@@ -253,11 +249,11 @@ describe('runCommand Integration & Dynamic Worker Sizing', () => {
     });
     it('correctly passes multiple specs to RustCoreBridge payload', async () => {
         vi.spyOn(TypeGenerator, 'writeDeclarationFiles').mockImplementation(() => { });
+        vi.spyOn(TypeGenerator, 'syncEnvDeclaration').mockResolvedValue(undefined);
         vi.spyOn(ConfigLoader, 'loadConfig').mockResolvedValue({
             webConfig: { baseUrl: 'http://localhost:3000' },
             androidConfig: {},
             iosConfig: {},
-            browsers: [],
             executionConfig: {},
         });
         let bridgeOptionsReceived = null;

package/dist/commands/init.d.ts

@@ -1,5 +1,5 @@
 export interface InitCommandOptions {
     force?: boolean;
-    template?: 'default' | 'nx';
+    template?: 'default' | 'nx' | 'react-component';
 }
 export declare function initCommand(options?: InitCommandOptions): Promise<void>;

package/dist/commands/init.js

@@ -215,10 +215,15 @@ export async function initCommand(options = {}) {
                     hint: 'Interactive workspace feature discovery & centralized config',
                 },
                 {
-                    label: 'Standard Project',
+                    label: 'Standard E2E Project',
                     value: 'default',
                     hint: 'Standalone single-suite E2E testing project',
                 },
+                {
+                    label: 'React Component Testing',
+                    value: 'react-component',
+                    hint: 'Real-browser React component testing with Vite & Testing Library',
+                },
             ],
         });
         if (p.isCancel(templateChoice)) {

package/dist/commands/run.js

@@ -125,6 +125,7 @@ export async function runCommand(specPaths, options = {}) {
     const effectiveSpecPaths = specPaths && specPaths.length > 0 ? specPaths : options.spec ? [options.spec] : undefined;
     // Ensure latest ambient types are up-to-date
     TypeGenerator.writeDeclarationFiles(cwd);
+    await TypeGenerator.syncEnvDeclaration(cwd);
     const home = process.env.HOME || process.env.USERPROFILE || '';
     const globalAppDataPath = path.join(home, '.testspectra');
     const appDataPath = options.workdir ? path.resolve(options.workdir) : globalAppDataPath;

package/dist/commands/sync-types.js

@@ -5,6 +5,7 @@ export async function syncTypesCommand(options = {}) {
     const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
     try {
         TypeGenerator.generateAll(cwd);
+        await TypeGenerator.syncEnvDeclaration(cwd);
         console.log(chalk.green('✔ Successfully synchronized TestSpectra ambient type declarations in .testspectra/types/'));
     }
     catch (err) {

package/dist/commands/test.d.ts

@@ -0,0 +1,17 @@
+export interface TestCommandOptions {
+    cwd?: string;
+    headed?: boolean;
+    headless?: boolean;
+    stepDelay?: string | number;
+    delay?: string | number;
+    spec?: string;
+    output?: string;
+    concurrency?: string | number;
+}
+/**
+ * `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
+ * docs/v2/features/component-testing/react/README.md §2 for why these are two independent
+ * runners rather than one extended pipeline.
+ */
+export declare function testCommand(options?: TestCommandOptions): Promise<void>;

package/dist/commands/test.js

@@ -0,0 +1,76 @@
+import path from 'node:path';
+import chalk from 'chalk';
+import * as p from '@clack/prompts';
+import { runSystemChecks } from './doctor.js';
+/**
+ * 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
+ * contain any browser-discovery logic of its own (see the package-level comment in
+ * tools/react/vitest.config.ts): this is the one place that resolves the path, passed down to
+ * the bundled Vitest/Playwright runner as a plain argument (env var), so component testing never
+ * requires a separate `playwright install` download alongside TestSpectra's own browser.
+ */
+async function resolveBrowserExecutable(cwd) {
+    try {
+        const { dependencies } = await runSystemChecks(cwd);
+        const chrome = dependencies.find((d) => d.category === 'web' && (d.name.includes('Chrome') || d.name.includes('Chromium')));
+        return chrome?.installed && chrome.location ? chrome.location : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `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
+ * docs/v2/features/component-testing/react/README.md §2 for why these are two independent
+ * runners rather than one extended pipeline.
+ */
+export async function testCommand(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    let reactPkg;
+    try {
+        reactPkg = await import('@testspectra/react');
+    }
+    catch {
+        p.log.error(chalk.red('✖ @testspectra/react is not installed in this workspace.'));
+        p.log.info(chalk.dim('Component testing requires the @testspectra/react package.'));
+        p.log.info(chalk.dim('  👉 Install it:  pnpm add -D @testspectra/react'));
+        process.exit(1);
+        return;
+    }
+    const browserExecutablePath = await resolveBrowserExecutable(cwd);
+    if (!browserExecutablePath) {
+        p.log.error(chalk.red('✖ TestSpectra-managed Chrome for Testing was not found.'));
+        p.log.info(chalk.dim('Component testing reuses the same browser install as `spectra run` (web).'));
+        p.log.info(chalk.dim('  👉 Install it:  spectra doctor --fix'));
+        process.exit(1);
+        return;
+    }
+    let stepDelayMs;
+    const rawDelay = options.stepDelay ?? options.delay;
+    if (rawDelay !== undefined) {
+        const delayNum = parseInt(String(rawDelay), 10);
+        if (!isNaN(delayNum) && delayNum >= 0) {
+            stepDelayMs = delayNum;
+        }
+    }
+    let headless = true;
+    if (options.headed) {
+        headless = false;
+    }
+    else if (options.headless !== undefined) {
+        headless = options.headless;
+    }
+    const concurrency = options.concurrency !== undefined ? parseInt(String(options.concurrency), 10) : undefined;
+    const ok = await reactPkg.runComponentTests({
+        cwd,
+        headless,
+        stepDelayMs,
+        spec: options.spec,
+        outputFile: options.output ? path.resolve(cwd, options.output) : undefined,
+        concurrency: concurrency !== undefined && !isNaN(concurrency) ? concurrency : undefined,
+        browserExecutablePath,
+    });
+    process.exit(ok ? 0 : 1);
+}

package/dist/commands/watch.js

@@ -3,15 +3,22 @@ import path from 'path';
 import chalk from 'chalk';
 import { TypeGenerator } from '../types/generator.js';
 export function startWatcher(cwd, debounceMs = 60) {
-    // Initial generation
+    // Initial generation. TypeGenerator.generateAll itself stays synchronous (reading
+    // spectra.config.ts is unavoidably async, so that part is handled by the separate
+    // syncEnvDeclaration call below); startWatcher stays sync so it can return the watcher handle
+    // immediately, with the async env sync fired-and-forgotten.
     TypeGenerator.generateAll(cwd);
+    TypeGenerator.syncEnvDeclaration(cwd).catch((err) => {
+        console.error(chalk.red(`✖ Error generating initial env.d.ts: ${err?.message}`));
+    });
     let debounceTimer = null;
     const triggerRegen = (filePath, eventType) => {
         if (debounceTimer)
             clearTimeout(debounceTimer);
-        debounceTimer = setTimeout(() => {
+        debounceTimer = setTimeout(async () => {
             try {
                 TypeGenerator.generateAll(cwd);
+                await TypeGenerator.syncEnvDeclaration(cwd);
                 const time = new Date().toLocaleTimeString();
                 const rel = path.relative(cwd, filePath) || filePath;
                 console.log(chalk.gray(`[${time}] `) + chalk.cyan(`✨ Updated ambient types `) + chalk.gray(`(${eventType}: ${rel})`));

package/dist/config/loader.js

@@ -89,7 +89,7 @@ export class ConfigLoader {
                 environmentVariables: overrides?.executionConfig?.environmentVariables ??
                     loaded.executionConfig?.environmentVariables ??
                     DEFAULT_CONFIG_DATA.executionConfig?.environmentVariables ??
-                    [],
+                    {},
             },
         };
     }

package/dist/config/schema.d.ts

@@ -20,19 +20,11 @@ export interface WebConfig {
     headless: boolean | 'new';
     /**
      * Implicit wait timeout (in milliseconds) for finding elements before throwing an error.
+     * Also the ceiling auto-waiting element assertions/actions poll against (capped at 2000ms for
+     * assertions — see `getAssertionTimeoutMs()`).
      * @default "5000"
      */
     implicitWait: string;
-    /**
-     * Maximum time (in milliseconds) allowed for a webpage to complete navigation and initial load.
-     * @default "30000"
-     */
-    pageLoadTimeout: string;
-    /**
-     * Maximum time (in milliseconds) allowed for asynchronous scripts to finish executing.
-     * @default "30000"
-     */
-    scriptTimeout: string;
     /**
      * Delay between consecutive actions and commands in milliseconds (slow motion).
      * @default 0
@@ -46,37 +38,6 @@ export interface WebConfig {
      */
     parallelizationMode: 'testcase' | 'suite';
 }
-/**
- * Browser target definition for web test execution.
- */
-export interface Browser {
-    /**
-     * Unique identifier for this browser configuration.
-     */
-    id: string;
-    /**
-     * Browser type/engine: `"chrome"`, `"firefox"`, `"safari"`, `"edge"`.
-     * @default "chrome"
-     */
-    type: string;
-    /**
-     * Whether to simulate mobile viewport and touch metrics.
-     * @default false
-     */
-    mobileEmulation: boolean;
-    /**
-     * Emulated device name when `mobileEmulation` is true (e.g. `"iPhone 14"`, `"Pixel 7"`).
-     */
-    deviceName?: string;
-    /**
-     * Custom browser window width in pixels.
-     */
-    width?: string;
-    /**
-     * Custom browser window height in pixels.
-     */
-    height?: string;
-}
 /**
  * Target Android device specification for multi-device parallel execution.
  */
@@ -260,40 +221,6 @@ export interface IosConfig {
      */
     parallelizationMode: 'testcase' | 'suite';
 }
-/**
- * Load testing stage ramp-up profile.
- */
-export interface LoadStage {
-    /**
-     * Stage identifier.
-     */
-    id: string;
-    /**
-     * Duration for this load stage (e.g. `"30s"`, `"2m"`).
-     */
-    duration: string;
-    /**
-     * Target virtual users (VUs) to scale to during this stage.
-     */
-    targetVUs: string;
-}
-/**
- * Performance and pass/fail metric threshold definition.
- */
-export interface SuccessThreshold {
-    /**
-     * Unique threshold identifier.
-     */
-    id: string;
-    /**
-     * Performance metric type (e.g. `"http_req_duration"`, `"http_req_failed"`).
-     */
-    metricType: string;
-    /**
-     * Maximum acceptable value (e.g. `"500ms"`, `"0.01"`).
-     */
-    maxValue: string;
-}
 /**
  * Specific domain filter for real-time network interception and recording.
  */
@@ -307,19 +234,6 @@ export interface MonitoredDomain {
      */
     enabled: boolean;
 }
-/**
- * Custom environment variable key-value pair injected into the test execution sandbox.
- */
-export interface EnvironmentVariable {
-    /**
-     * Environment variable name (e.g. `"API_SECRET_KEY"`).
-     */
-    key: string;
-    /**
-     * Environment variable value.
-     */
-    value: string;
-}
 /**
  * Test execution, CDP network monitoring, and sandbox environment configuration.
  */
@@ -344,9 +258,10 @@ export interface ExecutionConfig {
      */
     monitoredDomains?: MonitoredDomain[];
     /**
-     * Custom environment variables injected into the test process runtime.
+     * Custom environment variables injected into the test process runtime
+     * (e.g. `{ API_SECRET_KEY: "..." }`).
      */
-    environmentVariables?: EnvironmentVariable[];
+    environmentVariables?: Record<string, string>;
 }
 /**
  * Root configuration data structure matching TestSpectra project schema.
@@ -356,10 +271,6 @@ export interface ConfigData {
      * Web browser execution settings.
      */
     webConfig: WebConfig;
-    /**
-     * List of target browsers for web automation runs.
-     */
-    browsers: Browser[];
     /**
      * Android Appium driver and device options.
      */
@@ -368,21 +279,6 @@ export interface ConfigData {
      * iOS Appium driver and device options.
      */
     iosConfig: IosConfig;
-    /**
-     * Load testing parameters.
-     */
-    loadConfig: {
-        virtualUsers: string;
-        duration: string;
-    };
-    /**
-     * Load testing stages.
-     */
-    loadStages: LoadStage[];
-    /**
-     * Pass/fail metric thresholds.
-     */
-    thresholds: SuccessThreshold[];
     /**
      * Advanced execution and network recording settings.
      */

package/dist/config/schema.js

@@ -25,17 +25,8 @@ export const DEFAULT_CONFIG_DATA = {
         maxConcurrentSessions: '1',
         headless: true,
         implicitWait: '5000',
-        pageLoadTimeout: '30000',
-        scriptTimeout: '30000',
         parallelizationMode: 'testcase',
     },
-    browsers: [
-        {
-            id: 'chrome-desktop',
-            type: 'chrome',
-            mobileEmulation: false,
-        },
-    ],
     androidConfig: {
         driverServer: 'http://127.0.0.1:4800',
         appPackage: '',
@@ -70,17 +61,11 @@ export const DEFAULT_CONFIG_DATA = {
             },
         ],
     },
-    loadConfig: {
-        virtualUsers: '10',
-        duration: '1m',
-    },
-    loadStages: [],
-    thresholds: [],
     executionConfig: {
         networkMonitoringEnabled: true,
         fastResponseTime: '200',
         normalResponseTime: '1000',
         monitoredDomains: [],
-        environmentVariables: [],
+        environmentVariables: {},
     },
 };

package/dist/generator/__tests__/tsconfig-isolation.test.js

@@ -261,7 +261,7 @@ describe('Platform TSConfigs & Type Isolation (docs/v2/cli/tsconfig-platform-iso
         expect(threw).toBe(true);
         expect(errorMessage).toContain("Cannot find name 'AuthLoginPage'");
     });
-    it('E2E: compiles the full Nx monorepo template via tsc -b with 0 errors', () => {
+    it('E2E: compiles the full Nx monorepo template via tsc -b with 0 errors', async () => {
         let root = process.cwd();
         while (root && root !== path.dirname(root)) {
             if (fs.existsSync(path.join(root, 'pnpm-workspace.yaml')))
@@ -269,8 +269,12 @@ describe('Platform TSConfigs & Type Isolation (docs/v2/cli/tsconfig-platform-iso
             root = path.dirname(root);
         }
         const nxTemplateDir = path.join(root, 'cli', 'templates', 'nx');
-        // Generate latest ambient types for the nx template
+        // Generate latest ambient types for the nx template, including env.d.ts (a separate async
+        // step — see TypeGenerator.syncEnvDeclaration — since spectra.config.ts's
+        // executionConfig.environmentVariables is what the template's EnvironmentConfig suite
+        // exercises via the typed Env global).
         TypeGenerator.generateAll(nxTemplateDir);
+        await TypeGenerator.syncEnvDeclaration(nxTemplateDir);
         expect(() => {
             execSync(`npx tsc -b ${nxTemplateDir}`, { stdio: 'pipe' });
         }).not.toThrow();