@testspectra/cli — Architecture & Implementation

The TestSpectra CLI (spectra / testspectra) is the command-line orchestrator and developer tooling layer for the TestSpectra testing framework. It enables unified multi-platform test authoring (Web, Android, iOS), zero-import ambient typing, dynamic configuration, and high-performance native test execution powered by the Rust core runner.

1. Core Architecture Overview

                          ┌──────────────────────────┐
                          │    User Test Project     │
                          │ (Zero-Import TypeScript) │
                          └─────────────┬────────────┘
                                        │
                 ┌──────────────────────┴──────────────────────┐
                 │                                             │
                 ▼                                             ▼
     ┌──────────────────────┐                     ┌────────────────────────┐
     │  spectra run / CLI   │                     │ Solution TSConfigs     │
     │  (CLI Orchestration) │                     │ (tsconfig.*.json)      │
     └───────────┬──────────┘                     └────────────┬───────────┘
                 │                                             │
                 │ 1. Generates Ambient .d.ts                  │ 2. Isolated Platform
                 │    in .testspectra/types/                   │    Type Checking
                 ▼                                             ▼
     ┌──────────────────────┐                     ┌────────────────────────┐
     │  Core Test Runner    │                     │  Standard IDE & tsc    │
     │  (Rust Native Bin)   │                     │  (VS Code, Cursor, CI) │
     └──────────────────────┘                     └────────────────────────┘

2. Key Architectural Pillars

A. Zero-Import Multi-Platform Authoring

TestSpectra allows developers to write clean, boilerplate-free test specs, steps, actions, and page objects without manual import statements for globals or framework entities:

• Page Objects: LoginPage.login(...) and getters LoginPage.flashAlert resolve automatically based on target platform.
• Actions (Spectra.*): Built-in 16 atomic actions (Spectra.navigate, Spectra.click, Spectra.type, Spectra.select, Spectra.scroll, Spectra.swipe, Spectra.wait, etc.) matching TestSpectra database schema, merged seamlessly with user-defined custom actions (Spectra.verifyOtp).
• Direct Callable Assertions: Instant, auto-completed assertion methods available directly on WebdriverIO.Element, ChainablePromiseElement, and browser (shouldBeVisible(), shouldContainText(), shouldHaveValue(), shouldHaveUrl(), etc.).
• Steps: Step.loginUser(...) exposes shared business step flows.
• Fixtures: Fixture.userData provides typed, platform-agnostic test fixture access.
• WebdriverIO Globals: $, $$, browser, expect are available globally across all platforms.

B. Built-in Regular Actions & Direct Callable Assertions

TestSpectra provides a bundled, 100% database-schema-compatible library of built-in atomic actions and direct element assertions:

1. Direct Callable Element Assertions (should*)

All Page Object elements and locators support direct callable assertions without extra nesting:

it("should authenticate user using Page Objects and assertions", async () => {
  // Navigation & high-level business flows
  await LoginPage.open();
  await Step.loginUser("tomsmith", "SuperSecretPassword!");

  // Direct assertions on Page Object elements
  await LoginPage.flashAlert.shouldBeVisible();
  await LoginPage.flashAlert.shouldContainText("You logged into a secure area!");
  await LoginPage.usernameInput.shouldHaveValue("tomsmith");
});

Available Assertion Methods:

| Kategori | Method Callable | | :--- | :--- | | Visibility | await el.shouldBeVisible() / await el.shouldNotBeVisible() | | DOM Existence | await el.shouldExist() / await el.shouldNotExist() | | Element State | await el.shouldBeEnabled() / await el.shouldBeDisabled() / await el.shouldBeSelected() / await el.shouldBeChecked() | | Text Matching | await el.shouldHaveText(expected) / await el.shouldContainText(expected) | | Input Value | await el.shouldHaveValue(expected) / await el.shouldContainValue(expected) | | CSS Class | await el.shouldHaveClass(className) | | Attribute | await el.shouldHaveAttribute(name, val?) | | Browser URL / Title| await browser.shouldHaveUrl(url) / await browser.shouldHaveTitle(title) |

2. Built-in Atomic Actions (Spectra.*)

Available inside Page Objects, Actions, and Steps for raw element manipulation:

// Navigation
await Spectra.navigate("https://example.com/login");
await Spectra.back();
await Spectra.refresh();

// Interactions with Page Object getters or locators
await Spectra.type(this.usernameInput, "tomsmith");
await Spectra.click(this.submitButton);
await Spectra.select(this.countryDropdown, "ID");
await Spectra.clear(this.searchField);
await Spectra.pressKey("Enter");

// Gestures & Timing
await Spectra.scroll({ direction: "down", pixels: 300 });
await Spectra.swipe({ direction: "up", distance: 500 });
await Spectra.wait(1000);
await Spectra.waitForElement(this.flashAlert, 5000);

C. Platform Hierarchy & Resolution

Entities are structured with hierarchical platform stems:

page-objects/
  └── LoginPage/
        ├── web.ts          # Used for Web
        └── mobile.ts       # Fallback for Android and iOS

specs/
  └── TC-LOGIN-01/
        ├── web.test.ts     # Web spec
        ├── android.test.ts # Android spec
        └── ios.test.ts     # iOS spec

Resolution order:

• web: web → common
• android: android → mobile → common
• ios: ios → mobile → common
• mobile: mobile → common
• common: common

D. Solution-Style TypeScript Configuration & Language Service Plugin

To avoid ambient type clashes between platforms (such as different method signatures across Web and Mobile Page Objects), TestSpectra uses standard TypeScript Project References:

• tsconfig.json: Root project reference orchestrator with @testspectra/cli plugin registered.
• tsconfig.web.json: Scoped exclusively to Web files and .testspectra/types/web.d.ts.
• tsconfig.android.json: Scoped exclusively to Android files and .testspectra/types/android.d.ts.
• tsconfig.ios.json: Scoped exclusively to iOS files and .testspectra/types/ios.d.ts.
• fixtures.d.ts: Single platform-agnostic declaration file referenced by all platform declarations.

Zero-Terminal Background Type Generation (TS Plugin)

With the built-in TypeScript Server plugin (@testspectra/cli), background type generation is completely automatic:

• When you open the project in VS Code, Cursor, or WebStorm, the IDE's TypeScript Server automatically boots the @testspectra/cli Language Service plugin.
• The plugin generates and updates .testspectra/types/ ambient declarations in the background in real-time as you author Page Objects, Actions, Steps, and Fixtures.

Project verification is executed with standard tsc:

tsc -b

E. Typed Configuration with defineConfig

Configuration is strongly typed with full JSDoc documentation via spectra.config.ts:

import { defineConfig } from "@testspectra/cli";

export default defineConfig({
  webConfig: {
    baseUrl: "https://the-internet.herokuapp.com",
    headlessMode: true,
  },
  browsers: [
    { id: "chrome-desktop", type: "chrome" },
  ],
  androidConfig: {
    platformName: "Android",
    automationName: "UiAutomator2",
  },
});

3. CLI Commands

| Command | Description | | :--- | :--- | | spectra init / npx @testspectra/cli init | Interactive project setup. Auto-detects standalone or Nx Monorepos, discovers workspace packages from pnpm-workspace.yaml, and scaffolds centralized/distributed configurations. | | spectra add [module] | Adds a new TestSpectra E2E testing module to an existing workspace project or creates a new feature testing suite. | | spectra run [spec] | Automatically updates ambient declarations and invokes the native Rust test runner to execute the test suite. | | spectra doctor | Verifies local environment prerequisites (ADB, Java, Chrome, Bun, Node). | | spectra devices | Lists connected Android/iOS devices and local browsers. |

4. Standalone Project Directory Structure

├── spectra.config.ts            # Central typed project configuration
├── package.json                 # Scripts & dependencies
├── tsconfig.json                # Root solution references
├── tsconfig.web.json            # Web platform TypeScript scope
├── tsconfig.android.json        # Android platform TypeScript scope
├── tsconfig.ios.json            # iOS platform TypeScript scope
├── page-objects/                # Page Object Model folders
│   └── PlaygroundPage/
│         ├── web.ts
│         └── mobile.ts
├── support/
│   ├── actions/                 # Reusable atomic actions
│   │   └── fillCredentials/
│   │         ├── web.action.ts
│   │         └── mobile.action.ts
│   └── steps/                   # High-level business flows
│       └── verifyPlaygroundState/
│             ├── web.step.ts
│             └── mobile.step.ts
├── global-hooks/                # Global lifecycle hooks
│   └── before/
│         └── web.hook.ts
├── specs/                       # Layered zero-import test cases
│   └── Playground/
│         └── TC-0001-form-controls/
│               ├── web.test.ts
│               └── mobile.test.ts
├── fixtures/                    # Platform-agnostic test data
│   └── playgroundData.json
├── .testspectra/                # Auto-generated ambient typings & cache
│     └── types/
│           ├── fixtures.d.ts
│           ├── web.d.ts
│           ├── android.d.ts
│           ├── ios.d.ts
│           ├── mobile.d.ts
│           └── common.d.ts

5. Enterprise Monorepo Architecture (Nx & PNPM Workspace)

TestSpectra features an enterprise-grade architecture for large monorepos: "Centralized Configuration, Distributed Implementation".

                  ┌───────────────────────────────────────────────────────────┐
                  │                 Root Monorepo Directory                   │
                  │                                                           │
                  │  ├── spectra.config.ts       (Central Execution Config)   │
                  │  ├── .testspectra/           (Central Cache, AppData, Log)│
                  │  ├── pnpm-workspace.yaml     (Workspace Definition)       │
                  │  ├── nx.json                 (Nx Target & Caching Rules)  │
                  │  └── tsconfig.json           (Solution References)        │
                  └─────────────────────────────┬─────────────────────────────┘
                                                │
                 ┌──────────────────────────────┴──────────────────────────────┐
                 ▼                                                             ▼
  ┌───────────────────────────────┐                             ┌───────────────────────────────┐
  │   shared/testing/ (Library)   │                             │    packages/playground/e2e/   │
  ├───────────────────────────────┤                             ├───────────────────────────────┤
  │ - Shared Page Objects         │ ◄─── Auto-Scanned Globals ──│ - Feature Specs (specs/)      │
  │ - Shared Steps (verifyState)  │     (100% Zero-Import!)     │ - Feature Page Objects (POMs) │
  │ - Shared Actions (fillCreds)  │                             │ - project.json (Nx Target)    │
  │ - Shared Fixtures (playData)  │                             │ - tsconfig.web/android/ios    │
  └───────────────────────────────┘                             └───────────────────────────────┘

Key Pillars of Monorepo Integration:

1. Interactive Workspace Auto-Discovery (spectra init):

   • Parses pnpm-workspace.yaml (e.g. packages/*, modules/**).
   • Scans sub-directories for existing project.json or package.json.
   • Prompts the user with an interactive multi-select checkbox to choose which features will receive E2E testing.
   • Prompts for customizable E2E folder names (e.g. e2e, test/e2e) and the shared testing library path (shared/testing).

2. Centralized Configuration (spectra.config.ts) & App Data (.testspectra/):

   • spectra.config.ts lives exclusively at the root of the monorepo.
   • CLI test runs executed from sub-feature folders automatically traverse up to find the root configuration.
   • Driver caches, binaries, and logs reside in <root>/.testspectra/, preventing repository clutter across individual feature folders.

3. Global Zero-Import Consumption of Shared Library:

   • Entities placed inside shared/testing/page-objects/, shared/testing/support/steps/, shared/testing/support/actions/, and shared/testing/fixtures/ are automatically aggregated into ambient declarations.
   • Feature test specs consume shared Page Objects (PlaygroundPage.open()), steps (Step.verifyPlaygroundState()), actions (Spectra.fillCredentials()), and fixtures (Fixture.playgroundData) without a single line of import statement.

4. Nx Target Execution & Affected Caching:

   • Each feature E2E folder includes an Nx project.json:

     {
       "name": "playground-e2e",
       "targets": {
         "e2e": {
           "executor": "nx:run-commands",
           "options": { "command": "spectra run", "cwd": "packages/playground/e2e" },
           "configurations": {
             "android": { "command": "spectra run --target android" },
             "ios": { "command": "spectra run --target ios" },
             "headless": { "command": "spectra run --headless" }
           }
         }
       }
     }

   • Running nx run-many -t e2e executes all feature test suites in parallel.

5. Automatic Architecture Documentation (ARCHITECTURE.md):

   • Every spectra init run produces a comprehensive, project-tailored ARCHITECTURE.md file in the root workspace.
   • It documents the generated file map, exact distributed feature paths, shared library resolution, and zero-import mechanics for onboarding engineers.

6. Development & Verification

To verify the CLI and example app:

# Build CLI
pnpm --filter @testspectra/cli build

# Test interactive scaffolding
npx @testspectra/cli init
pnpm type-check