@testspectra/cli 1.0.7 → 1.0.10

package/CLI_IMPLEMENTATION_PLAN.md

@@ -1,369 +0,0 @@
-# TestSpectra CLI (`@testspectra/cli`) Implementation Plan
-
-## 1. Overview
-The TestSpectra CLI provides a zero-config, command-line interface for running Web and Mobile (Android/iOS) test suites using the shared Rust core runner (`core/test-runner` and `core/device-manager`).
-
-The CLI configuration strictly adheres to the backend `ProjectConfig` and `ConfigData` schema (`backend/src/models/project_config.rs` and `src/services/project-config-service.ts`).
-
----
-
-## 2. Architecture
-
-```
-                       ┌─────────────────────────────────┐
-                       │    TypeScript CLI (`cli/`)       │
-                       │  (commander / inquirer / ora)   │
-                       └────────────────┬────────────────┘
-                                        │
-                       ┌────────────────┴────────────────┐
-                       ▼                                 ▼
-              Local Execution                   Remote Execution
-       ┌─────────────────────────────┐   ┌─────────────────────────────┐
-       │ NAPI-RS / Subprocess Bridge │   │   HTTP REST API Client      │
-       │ to core/test-runner (Rust)  │   │   to Backend API Server     │
-       └──────────────┬──────────────┘   └──────────────┬──────────────┘
-                      │                                 │
-                      ▼                                 ▼
-          ┌───────────────────────┐         ┌───────────────────────┐
-          │ core/test-runner      │         │ Backend API           │
-          │ (Rust Engine)         │         │ (PostgreSQL + Engine) │
-          └───────────────────────┘         └───────────────────────┘
-```
-
----
-
-## 3. Package & File Structure
-
-```
-testspectra-source/
-└── cli/
-    ├── README.md
-    ├── CLI_IMPLEMENTATION_PLAN.md    <-- This Plan
-    ├── package.json
-    ├── tsconfig.json
-    ├── bin/
-    │   └── testspectra.js
-    └── src/
-        ├── index.ts                  # Main entrypoint & Commander setup
-        ├── config/
-        │   ├── schema.ts             # Exact ConfigData & ProjectConfig TypeScript types
-        │   └── loader.ts             # Config resolution (file vs remote vs CLI flags)
-        ├── commands/
-        │   ├── init.ts               # Generate default testspectra.config.json
-        │   ├── run.ts                # Execute test cases/suites
-        │   ├── devices.ts            # List connected Android/iOS/Web devices
-        │   └── doctor.ts             # System diagnostic check (ADB, Appium, Java, Browsers)
-        ├── runner/
-        │   ├── bridge.ts             # Interface to Rust core runner binary/NAPI
-        │   └── reporter.ts           # Spec, JSON, & JUnit XML reporters
-        └── api/
-            └── client.ts             # REST client for sync with backend project config
-```
-
----
-
-## 4. Configuration Schema (`cli/src/config/schema.ts`)
-
-Matches `backend/src/models/project_config.rs` and `src/services/project-config-service.ts`:
-
-```typescript
-export interface WebConfig {
-  baseUrl: string;
-  maxConcurrentSessions: string;
-  headlessMode: boolean;
-  implicitWait: string;
-  pageLoadTimeout: string;
-  scriptTimeout: string;
-  parallelizationMode: "testcase" | "suite";
-}
-
-export interface AndroidConfig {
-  appiumServer: string;
-  platformName: string;
-  platformVersion: string;
-  deviceName: string;
-  automationName: string;
-  appPackage: string;
-  appActivity: string;
-  autoGrantPermissions: boolean;
-  noReset: boolean;
-  implicitWait: string;
-  parallelizationMode: "testcase" | "suite";
-}
-
-export interface IosConfig {
-  appiumServer: string;
-  platformName: string;
-  platformVersion: string;
-  deviceName: string;
-  automationName: string;
-  bundleId: string;
-  udid: string;
-  xcodeOrgId: string;
-  xcodeSigningId: string;
-  autoAcceptAlerts: boolean;
-  noReset: boolean;
-  implicitWait: string;
-  parallelizationMode: "testcase" | "suite";
-}
-
-export interface ConfigData {
-  webConfig: WebConfig;
-  browsers: Array<{
-    id: string;
-    type: string;
-    mobileEmulation: boolean;
-    deviceName?: string;
-    width?: string;
-    height?: string;
-  }>;
-  androidConfig: AndroidConfig;
-  iosConfig: IosConfig;
-  loadConfig: {
-    virtualUsers: string;
-    duration: string;
-  };
-  loadStages: Array<{
-    id: string;
-    duration: string;
-    targetVUs: string;
-  }>;
-  thresholds: Array<{
-    id: string;
-    metricType: string;
-    maxValue: string;
-  }>;
-  executionConfig?: {
-    networkMonitoringEnabled: boolean;
-    fastResponseTime: string;
-    normalResponseTime: string;
-    monitoredDomains?: Array<{ domain: string; enabled: boolean }>;
-    environmentVariables?: Array<{ key: string; value: string }>;
-  };
-}
-
-export interface ProjectConfig {
-  project_id: string;
-  config_data: ConfigData;
-  updated_at?: string;
-}
-```
-
----
-
-## 5. Key CLI Commands & Features
-
-| Command | Arguments / Flags | Description |
-|---|---|---|
-| `testspectra init` | `--force` | Generate default `testspectra.config.json` adhering to `ConfigData`. |
-| `testspectra doctor` | `--fix` | Diagnostic check for ADB, Appium, Chrome, Java, Node. |
-| `testspectra devices` | `--target <android\|ios\|web>` | List connected devices & available browsers. |
-| `testspectra run` | `<path>` `--target <target>` `--remote` `--project-id <id>` | Run test cases/suites via local config or remote backend config. |
-
----
-
-## 6. Execution Flow & Driver Management
-
-1. **Base Directory Resolution (`app_data_path`):**
-   - CLI sets `RunnerContext.app_data_path` to `./.testspectra` inside the target project root (overridable via `--workdir`).
-   - Driver cache automatically lands in `./.testspectra/driver_cache`.
-   - Desktop Tauri app uses OS AppSupport (`~/Library/Application Support/...`), while CLI isolates everything inside project `.testspectra`.
-
-2. **Initialization:** CLI resolves config via local `testspectra.config.json` or fetches `ProjectConfig` from backend.
-3. **Environment Validation:** Verifies Appium / ADB readiness using `core/device-manager`.
-4. **Execution & Driver Auto-Recovery:**
-   - Pass resolved `ConfigData` JSON + test files payload into `core/test-runner` Rust engine via NAPI bridge or subprocess IPC stream.
-   - `core/test-runner` automatically monitors for Chromedriver download failures, wipes `./.testspectra/driver_cache`, and retries once transparently.
-5. **Reporting:** Stream real-time logs and output JUnit / Spec formatted result.
-
----
-
-## 7. Refactoring Plan: Moving Shared Core Features from `src-tauri` to `core/`
-
-To avoid code duplication and support CLI/Server environments natively, the following features will be refactored from `src-tauri` into the shared `core` workspace:
-
-### A. ADB Wireless & Pairing (`src-tauri/src/adb.rs` → `core/device-manager`)
-- **Current State:** High-level device discovery and auto-reconnection loop (`get_adb_devices_impl`) live in `src-tauri/src/adb.rs` while primitive ADB calls live in `core/device-manager`.
-- **Target Architecture:**
-  - Move stateful device tracking & background auto-reconnection into `core/device-manager::android`.
-  - Provide headless Rust/C-API/NAPI methods (`get_adb_devices`, `pair_adb_device`, `start_qr_pairing`) accessible to both Tauri app and `testspectra devices pair` CLI command.
-
-### B. Dependency Check & Installer (`src-tauri/src/dependencies.rs` → `core/test-runner`)
-- **Current State:** `src-tauri/src/dependencies.rs` wraps `testspectra_core_runner::dependency` with Tauri `AppHandle` events for emitting install logs.
-- **Target Architecture:**
-  - Decouple log emission using a generic callback/channel pattern (`fn(log: DependencyLog)`).
-  - Move full dependency resolution & auto-installer (`install_missing_dependencies`) into `core/test-runner::dependency`.
-  - Tauri UI subscribes via channel; CLI `testspectra doctor --fix` renders progress directly to terminal stdout/stderr via `ora` spinner / progress bar.
-
----
-
-## 8. Multi-Platform Hierarchy & Ambient Type Resolution
-
-TestSpectra scripts are organized natively by **Entity Folders** supporting multi-platform hierarchy resolution (as defined in `docs/features/v1.3-MULTI_PLATFORM_AUTOMATION.md`):
-
-### A. Resolution Hierarchy (Highest to Lowest Priority)
-| Target Context / Spec | Hierarchy Chain |
-| :--- | :--- |
-| **Web Context (`web.test.ts`)** | `*.web.ts` &rarr; `*.common.ts` (or `*.ts` fallback) |
-| **iOS Context (`ios.test.ts`)** | `*.ios.ts` &rarr; `*.mobile.ts` &rarr; `*.common.ts` |
-| **Android Context (`android.test.ts`)** | `*.android.ts` &rarr; `*.mobile.ts` &rarr; `*.common.ts` |
-| **Mobile Context (`mobile.test.ts`)** | `*.mobile.ts` &rarr; `*.common.ts` |
-| **Common Context (`common.test.ts`)** | `*.common.ts` (Strict base only) |
-
-### B. Ambient Global Resolution in Specs (Zero Manual Imports)
-TestSpectra execution preparer (`core/test-runner`) and the CLI Type Generator (`cli::TypeGenerator`) synthesize global ambient declarations (`.testspectra/types/{web,android,ios,mobile,common}.d.ts`) so specs never need manual imports for Page Objects, Actions, Steps, or Fixtures:
-- **`LoginPage.open()`** &rarr; Ambiently declared via `declare const LoginPage: typeof import('../page-objects/LoginPage/web.js').default;`
-- **`Spectra.actionName()`** &rarr; Ambiently declared per platform from `actions/`.
-- **`Step.stepName()`** &rarr; Ambiently declared per platform from `steps/`.
-- **`Fixture.fixtureName`** &rarr; Ambiently declared from `fixtures/` assets.
-- **`browser.intercept()`** &rarr; Ambiently declared on `WebdriverIO.Browser`.
-
-No custom VS Code language server plugin or extension is required. Standard TypeScript compiler (`tsc`) and standard IDEs (VS Code, Cursor, WebStorm) handle everything natively via the platform tsconfigs.
-
-## 9. Standard TestSpectra Multi-Platform Project Structure & Platform-Isolated TSConfigs
-
-To ensure 100% accurate TypeScript type resolution without collisions across platform signatures (e.g. `login(u,p)` on Web vs `login(u,p,captcha)` on Mobile), TestSpectra uses **Platform-Isolated TSConfigs**:
-
-```text
-my-test-project/
-├── tsconfig.json                     # Solution root pointing to platform tsconfigs
-├── tsconfig.web.json                 # Web TS context (web specs + web.d.ts + common.d.ts)
-├── tsconfig.android.json             # Android TS context (android specs + android.d.ts + mobile.d.ts + common.d.ts)
-├── tsconfig.ios.json                 # iOS TS context (ios specs + ios.d.ts + mobile.d.ts + common.d.ts)
-├── spectra.config.ts                 # Matching backend ConfigData schema (typed with defineConfig)
-├── .testspectra/                     # Local TestSpectra runtime & types (ignored in git)
-│   ├── types/
-│   │   ├── web.d.ts                  # Generated ambient types for web
-│   │   ├── android.d.ts              # Generated ambient types for android
-│   │   ├── ios.d.ts                  # Generated ambient types for ios
-│   │   └── common.d.ts               # Generated ambient types for common
-│   └── driver_cache/                 # Managed Chromedriver / Appium cache
-│
-├── specs/                            # Entity folder per Test Case
-│   └── TC-LOGIN-01/
-│       ├── web.test.ts               # Web implementation (zero-import single it block)
-│       ├── android.test.ts           # Android implementation
-│       └── ios.test.ts               # iOS implementation
-│
-├── page-objects/                     # Entity folder per Page Object
-│   └── LoginPage/
-│       ├── web.ts                    # Web Page Object implementation
-│       └── mobile.ts                 # Shared mobile Page Object implementation
-│
-├── actions/                          # Entity folder per Action
-│   └── verifyOtp/
-│       ├── web.action.ts
-│       └── mobile.action.ts
-│
-├── steps/                            # Entity folder per Step
-│   └── loginUser/
-│       ├── web.step.ts
-│       └── mobile.step.ts
-│
-├── fixtures/                         # Test assets (JSON, PNG, CSV)
-│   └── userData.json
-│
-└── hooks/                            # Per-suite lifecycle hooks
-    └── default/
-        ├── before.web.hook.ts
-        ├── before.android.hook.ts
-        └── before.ios.hook.ts
-```
-
-### Complete Scaffolding on `spectra init`
-Running `spectra init` automatically scaffolds:
-1. `spectra.config.ts` using `defineConfig`.
-2. Root `tsconfig.json` & platform-isolated `tsconfig.web.json`, `tsconfig.android.json`, `tsconfig.ios.json`.
-3. Complete boilerplate templates for **Page Objects**, **Specs**, **Actions**, **Steps**, **Fixtures**, and **Suite Hooks**.
-4. `.gitignore` ensuring `.testspectra/`, `dist/`, and `node_modules/` are not committed.
-5. All scaffolded templates pass TypeScript checking with **0 errors**.
-
-  3. Updates TypeScript triple-slash references if necessary.
-
-### B. Dependencies Location & Isolation (`node_modules`)
-- CLI isolates WebdriverIO & Appium dependencies into `./.testspectra/node_modules` (or uses root `node_modules` if a `package.json` is present).
-- Ensures user test projects don't need a manually managed `package.json` unless desired.
-
----
-
-## 11. Custom Browser Commands & Fixture-Integrated Interceptor (`browser.intercept`)
-
-TestSpectra extends WebdriverIO's `browser` object with runtime custom commands bundled directly in `core/test-runner` execution preparer (keeping user `wdio.conf.ts` completely clean).
-
-### A. Feature Capabilities
-- **`browser.intercept(path, method, fixture?, options?)`**: Strongly-typed API mock interceptor.
-- **Fixture Object Integration:** Accepts `Fixture.sampleJson` asset references directly, auto-loading and parsing files from `fixtures/`.
-- **Dynamic `mock.respondWith()`**: Allows updating mock responses on the fly within individual test steps.
-
-### B. Type Declarations (`cli/src/types/webdriverio.d.ts`)
-```typescript
-declare global {
-  namespace WebdriverIO {
-    export interface InterceptFixtureOptions {
-      statusCode?: number;
-      headers?: Record<string, string>;
-    }
-
-    export interface InterceptFixtureObject<TData = unknown> {
-      statusCode?: number;
-      body: TData;
-      headers?: Record<string, string>;
-    }
-
-    export type InterceptInput<TData = unknown> =
-      | InterceptFixtureObject<TData>
-      | TData
-      | string;
-
-    interface Mock {
-      /**
-       * Dynamically set or change the fixture response for this mock instance.
-       * Supports Fixture paths, `{ statusCode, body, headers }` objects, or raw payloads.
-       */
-      respondWith<TData = unknown>(
-        fixture: InterceptInput<TData>,
-        options?: InterceptFixtureOptions,
-      ): Promise<void>;
-    }
-
-    interface Browser {
-      /**
-       * Clean & strongly-typed API interceptor for WebdriverIO.
-       * Automatically resolves relative path against browser.options.baseUrl.
-       * Integrated directly with TestSpectra Fixtures.
-       */
-      intercept<TData = unknown>(
-        path: string,
-        method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH',
-        fixture?: InterceptInput<TData>,
-        options?: InterceptFixtureOptions,
-      ): Promise<Mock>;
-    }
-  }
-}
-```
-
-### C. Usage Example in Test Files
-```typescript
-test('intercept user API using TestSpectra Fixtures', async () => {
-  // Pass Fixture asset directly
-  await browser.intercept('/api/users', 'GET', Fixture.usersListJson);
-
-  // Pass Fixture object with custom status code
-  await browser.intercept('/api/login', 'POST', {
-    statusCode: 401,
-    body: { error: 'Invalid credentials' }
-  });
-
-  // Dynamic response update
-  const userMock = await browser.intercept('/api/profile', 'GET');
-  await userMock.respondWith(Fixture.adminProfileJson, { statusCode: 200 });
-});
-```
-
----
-
-### C. Test Output & Reports (Real-Time Stdout + Local JSON Export)
-For local CLI runs, test execution provides real-time feedback and JSON persistence:
-- **Terminal Stdout:** Real-time colored stdout stream of step `TestLog` entries.
-- **Local JSON Output:** Saves complete `TestRunResult` payload (`status`, `duration`, `logs`, CDP `networkResources`) to `./.testspectra/reports/result.json` (or custom path via `--output <path>`).

package/src/commands/devices.ts

@@ -1,41 +0,0 @@
-import { execSync } from "child_process";
-
-export async function devicesCommand(options: { target?: "android" | "ios" | "web" | "all" }) {
-  const target = options.target || "all";
-  console.log(`\x1b[36m[TestSpectra Devices]\x1b[0m Listing connected test targets (scope: ${target})...\n`);
-
-  if (target === "all" || target === "android") {
-    console.log("\x1b[1mAndroid Devices (ADB):\x1b[0m");
-    try {
-      const adbOutput = execSync("adb devices -l", { stdio: "pipe" }).toString();
-      const lines = adbOutput.split("\n").slice(1);
-      let found = false;
-      for (const line of lines) {
-        if (line.trim()) {
-          found = true;
-          console.log(`  \x1b[32m•\x1b[0m ${line.trim()}`);
-        }
-      }
-      if (!found) {
-        console.log("  \x1b[90mNo Android devices/emulators connected via ADB.\x1b[0m");
-      }
-    } catch {
-      console.log("  \x1b[31mADB command failed or platform-tools not in PATH.\x1b[0m");
-    }
-  }
-
-  if (target === "all" || target === "web") {
-    console.log("\n\x1b[1mWeb Browsers:\x1b[0m");
-    try {
-      const chromeVer = execSync(
-        process.platform === "darwin"
-          ? '"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --version'
-          : "google-chrome --version",
-        { stdio: "pipe" }
-      ).toString().trim();
-      console.log(`  \x1b[32m•\x1b[0m Chrome: ${chromeVer}`);
-    } catch {
-      console.log("  \x1b[90m• Chrome: Not installed\x1b[0m");
-    }
-  }
-}

package/src/commands/doctor.ts

@@ -1,57 +0,0 @@
-import { execSync } from "child_process";
-
-export async function doctorCommand(options: { fix?: boolean }) {
-  console.log("\x1b[36m[TestSpectra Doctor]\x1b[0m Checking development and runtime dependencies...\n");
-
-  const checks = [
-    {
-      name: "Node.js",
-      command: "node -v",
-      required: true,
-    },
-    {
-      name: "Bun",
-      command: "bun -v",
-      required: false,
-    },
-    {
-      name: "ADB (Android Debug Bridge)",
-      command: "adb version",
-      required: false,
-    },
-    {
-      name: "Java JDK",
-      command: "java -version",
-      required: false,
-    },
-    {
-      name: "Google Chrome",
-      command: process.platform === "darwin"
-        ? '"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --version'
-        : "google-chrome --version",
-      required: false,
-    },
-  ];
-
-  let missingCount = 0;
-
-  for (const check of checks) {
-    try {
-      const out = execSync(check.command, { stdio: "pipe" }).toString().trim();
-      const firstLine = out.split("\n")[0];
-      console.log(` \x1b[32m✓\x1b[0m ${check.name.padEnd(30)} \x1b[90m(${firstLine})\x1b[0m`);
-    } catch {
-      console.log(` \x1b[31m✗\x1b[0m ${check.name.padEnd(30)} \x1b[31m(Not found)\x1b[0m`);
-      if (check.required) {
-        missingCount++;
-      }
-    }
-  }
-
-  console.log("\n------------------------------------------------------------");
-  if (missingCount === 0) {
-    console.log("\x1b[32m[Doctor]\x1b[0m System ready for local test execution!");
-  } else {
-    console.log(`\x1b[33m[Doctor]\x1b[0m Found ${missingCount} missing required dependencies.`);
-  }
-}