@testspectra/cli 1.1.8-rc.18 → 1.1.8-rc.20

package/templates/nx/package.json

@@ -12,8 +12,8 @@
     "postinstall": "spectra sync-types"
   },
   "devDependencies": {
-    "@testspectra/cli": "^1.1.8-rc.18",
-    "@testspectra/matchers": "^1.1.8-rc.18",
+    "@testspectra/cli": "^1.1.8-rc.20",
+    "@testspectra/matchers": "^1.1.8-rc.20",
     "@types/node": "^20.14.0",
     "@wdio/cli": "^9.2.8",
     "@wdio/local-runner": "^9.2.8",

package/templates/react-component/package.json

@@ -14,9 +14,9 @@
     "postinstall": "spectra sync-types"
   },
   "devDependencies": {
-    "@testspectra/cli": "^1.1.8-rc.18",
-    "@testspectra/matchers": "^1.1.8-rc.18",
-    "@testspectra/react": "^1.1.8-rc.18",
+    "@testspectra/cli": "^1.1.8-rc.20",
+    "@testspectra/matchers": "^1.1.8-rc.20",
+    "@testspectra/react": "^1.1.8-rc.20",
     "@types/node": "^20.14.0",
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",

package/bin/.testspectra-runner.hash

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

package/dist/commands/__tests__/cloud-run.test.d.ts

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

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

@@ -1,93 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { cloudRunCommand, parseTimeoutMs } from '../cloud-run.js';
-const ORIGINAL_ENV = { ...process.env };
-function mockFetchSequence(responses) {
-    let call = 0;
-    return vi.fn(async (_url, _init) => {
-        const res = responses[Math.min(call, responses.length - 1)];
-        call += 1;
-        return {
-            ok: res.ok,
-            status: res.status ?? (res.ok ? 200 : 500),
-            statusText: 'error',
-            json: async () => res.json,
-        };
-    });
-}
-describe('cloudRunCommand (docs/v2/cloud/git-spec-standards-and-workflow.md)', () => {
-    beforeEach(() => {
-        process.env = { ...ORIGINAL_ENV, SPECTRA_URL: 'https://cloud.test', SPECTRA_TOKEN: 'gitea-pat-123' };
-        process.exitCode = undefined;
-        vi.useFakeTimers();
-    });
-    afterEach(() => {
-        process.env = { ...ORIGINAL_ENV };
-        vi.restoreAllMocks();
-        vi.useRealTimers();
-    });
-    it('fails fast without SPECTRA_URL/SPECTRA_TOKEN', async () => {
-        delete process.env.SPECTRA_URL;
-        delete process.env.SPECTRA_TOKEN;
-        const fetchSpy = vi.fn();
-        vi.stubGlobal('fetch', fetchSpy);
-        await cloudRunCommand({ project: 'org/repo', branch: 'main' });
-        expect(process.exitCode).toBe(1);
-        expect(fetchSpy).not.toHaveBeenCalled();
-    });
-    it('triggers and returns immediately with --no-wait', async () => {
-        const fetchSpy = mockFetchSequence([{ ok: true, json: { job_id: 'job-1', status: 'queued' } }]);
-        vi.stubGlobal('fetch', fetchSpy);
-        await cloudRunCommand({ project: 'org/repo', branch: 'main', wait: false });
-        expect(fetchSpy).toHaveBeenCalledTimes(1);
-        const [url, init] = fetchSpy.mock.calls[0];
-        expect(url).toBe('https://cloud.test/api/v1/runs/trigger');
-        const headers = init.headers;
-        expect(headers.Authorization).toBe('Bearer gitea-pat-123');
-        expect(JSON.parse(init.body)).toMatchObject({ project_id: 'org/repo', branch: 'main', platform: 'web' });
-        expect(process.exitCode).toBeUndefined();
-    });
-    it('exits 0 when the job reaches done', async () => {
-        const fetchSpy = mockFetchSequence([
-            { ok: true, json: { job_id: 'job-2', status: 'queued' } },
-            { ok: true, json: { status: 'done', run_id: 'run-2', started_at: null, completed_at: null, error_log: null } },
-        ]);
-        vi.stubGlobal('fetch', fetchSpy);
-        const promise = cloudRunCommand({ project: 'org/repo', branch: 'main' });
-        await vi.advanceTimersByTimeAsync(5000);
-        await promise;
-        expect(process.exitCode).toBe(0);
-    });
-    it('exits 1 when the job reaches failed', async () => {
-        const fetchSpy = mockFetchSequence([
-            { ok: true, json: { job_id: 'job-3', status: 'queued' } },
-            {
-                ok: true,
-                json: { status: 'failed', run_id: 'run-3', started_at: null, completed_at: null, error_log: 'boom' },
-            },
-        ]);
-        vi.stubGlobal('fetch', fetchSpy);
-        const promise = cloudRunCommand({ project: 'org/repo', branch: 'main' });
-        await vi.advanceTimersByTimeAsync(5000);
-        await promise;
-        expect(process.exitCode).toBe(1);
-    });
-    it('exits 1 when the trigger request itself fails', async () => {
-        const fetchSpy = mockFetchSequence([{ ok: false, status: 401, json: { error: 'Invalid PAT' } }]);
-        vi.stubGlobal('fetch', fetchSpy);
-        await cloudRunCommand({ project: 'org/repo', branch: 'main' });
-        expect(process.exitCode).toBe(1);
-    });
-});
-describe('parseTimeoutMs', () => {
-    it('parses seconds, minutes, and hours', () => {
-        expect(parseTimeoutMs('30s')).toBe(30_000);
-        expect(parseTimeoutMs('30m')).toBe(30 * 60_000);
-        expect(parseTimeoutMs('2h')).toBe(2 * 3_600_000);
-    });
-    it('defaults to minutes when no unit is given', () => {
-        expect(parseTimeoutMs('10')).toBe(10 * 60_000);
-    });
-    it('falls back to 30m for unparseable input', () => {
-        expect(parseTimeoutMs('nonsense')).toBe(30 * 60_000);
-    });
-});

package/dist/commands/cloud-run.d.ts

@@ -1,13 +0,0 @@
-export interface CloudRunOptions {
-    project: string;
-    projectName?: string;
-    branch?: string;
-    commit?: string;
-    platform?: string;
-    wait?: boolean;
-    timeout?: string;
-    demo?: boolean;
-    baseUrl?: string;
-}
-export declare function parseTimeoutMs(timeout: string): number;
-export declare function cloudRunCommand(options: CloudRunOptions): Promise<void>;

package/dist/commands/cloud-run.js

@@ -1,120 +0,0 @@
-import { execFileSync } from 'child_process';
-import chalk from 'chalk';
-import ora from 'ora';
-const POLL_INTERVAL_MS = 5000;
-const DEFAULT_TIMEOUT = '30m';
-function detectGitRef(...args) {
-    try {
-        return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-export function parseTimeoutMs(timeout) {
-    const match = /^(\d+)(s|m|h)?$/.exec(timeout.trim());
-    if (!match)
-        return 30 * 60 * 1000;
-    const value = Number(match[1]);
-    const unit = match[2] ?? 'm';
-    const multiplier = unit === 's' ? 1000 : unit === 'h' ? 3_600_000 : 60_000;
-    return value * multiplier;
-}
-// Same credential path as the trigger endpoint expects: a Gitea PAT, not the
-// dashboard's OAuth2 session — a CI runner can't complete a browser redirect.
-// See docs/v2/cloud/git-spec-standards-and-workflow.md.
-function requireEnv(name) {
-    const value = process.env[name];
-    if (!value) {
-        console.error(chalk.red(`Missing required environment variable: ${name}`));
-        console.error(chalk.gray('Set it as a CI secret — see docs/v2/cloud/git-spec-standards-and-workflow.md'));
-    }
-    return value;
-}
-export async function cloudRunCommand(options) {
-    const spectraUrl = requireEnv('SPECTRA_URL')?.replace(/\/$/, '');
-    const spectraToken = requireEnv('SPECTRA_TOKEN');
-    if (!spectraUrl || !spectraToken) {
-        process.exitCode = 1;
-        return;
-    }
-    const branch = options.branch ?? detectGitRef('rev-parse', '--abbrev-ref', 'HEAD');
-    if (!branch) {
-        console.error(chalk.red('Could not determine branch: pass --branch or run inside a git repository.'));
-        process.exitCode = 1;
-        return;
-    }
-    const commit = options.commit ?? detectGitRef('rev-parse', 'HEAD');
-    const platform = options.platform ?? 'web';
-    const wait = options.wait !== false;
-    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
-    const spinner = ora(`Triggering cloud run for ${chalk.bold(options.project)}@${branch}...`).start();
-    let trigger;
-    try {
-        const res = await fetch(`${spectraUrl}/api/v1/runs/trigger`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                Authorization: `Bearer ${spectraToken}`,
-            },
-            body: JSON.stringify({
-                project_id: options.project,
-                project_name: options.projectName ?? options.project,
-                branch,
-                commit_hash: commit,
-                platform,
-                demo: options.demo ?? false,
-                base_url: options.baseUrl,
-            }),
-        });
-        if (!res.ok) {
-            const body = await res.json().catch(() => ({ error: res.statusText }));
-            throw new Error(body.error ?? `HTTP ${res.status}`);
-        }
-        trigger = (await res.json());
-    }
-    catch (err) {
-        spinner.fail(chalk.red(`Failed to trigger cloud run: ${err.message}`));
-        process.exitCode = 1;
-        return;
-    }
-    spinner.succeed(`Cloud run queued: ${chalk.cyan(trigger.job_id)}`);
-    if (!wait) {
-        console.log(chalk.gray(`Not waiting for result. Poll ${spectraUrl}/api/v1/jobs/${trigger.job_id}/status yourself.`));
-        return;
-    }
-    await waitForJob(spectraUrl, spectraToken, trigger.job_id, timeout);
-}
-async function waitForJob(spectraUrl, spectraToken, jobId, timeout) {
-    const spinner = ora('Waiting for run to finish...').start();
-    const deadline = Date.now() + parseTimeoutMs(timeout);
-    while (Date.now() < deadline) {
-        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
-        let job;
-        try {
-            const res = await fetch(`${spectraUrl}/api/v1/jobs/${jobId}/status`, {
-                headers: { Authorization: `Bearer ${spectraToken}` },
-            });
-            if (!res.ok)
-                throw new Error(`HTTP ${res.status}`);
-            job = (await res.json());
-        }
-        catch (err) {
-            spinner.text = chalk.yellow(`Poll failed, retrying: ${err.message}`);
-            continue;
-        }
-        if (job.status === 'done') {
-            spinner.succeed(chalk.green(`Run passed (run_id: ${job.run_id})`));
-            process.exitCode = 0;
-            return;
-        }
-        if (job.status === 'failed') {
-            spinner.fail(chalk.red(`Run failed (run_id: ${job.run_id})${job.error_log ? `: ${job.error_log}` : ''}`));
-            process.exitCode = 1;
-            return;
-        }
-        spinner.text = `Run status: ${job.status}`;
-    }
-    spinner.fail(chalk.red(`Timed out after ${timeout} waiting for the run to finish.`));
-    process.exitCode = 1;
-}

package/templates/docs/ARCHITECTURE.default.md

@@ -1,26 +0,0 @@
-# TestSpectra Project Architecture
-
-This project is built with the TestSpectra testing framework.
-
-## Structure & File Map
-- `./spectra.config.ts`: Typed runner configuration.
-- `./specs/`: Layered test cases (`specs/<Suite>/<CaseId>/` with `web.test.ts`, `android.test.ts`, `ios.test.ts`).
-- `./page-objects/`: Page Object models per platform.
-- `./support/steps/`: Business flows accessible globally via `Step.*`.
-- `./support/actions/`: Atomic actions accessible globally via `Spectra.*`.
-- `./fixtures/`: JSON fixtures accessible globally via `Fixture.*`.
-- `./global-hooks/`: Global suite lifecycle hooks.
-- `./.testspectra/`: Auto-generated ambient typings and local runtime cache.
-
-## Execution
-```bash
-# Run web test suite
-pnpm test
-
-# Run Android / iOS
-pnpm spectra run --target android
-pnpm spectra run --target ios
-
-# Type check
-pnpm type-check
-```

package/templates/docs/ARCHITECTURE.nx.md

@@ -1,119 +0,0 @@
-# TestSpectra Enterprise Monorepo Architecture
-
-This workspace uses TestSpectra's **"Centralized Configuration, Distributed Implementation"** model for automated cross-platform testing.
-
----
-
-## 1. Directory & File Overview
-
-### Centralized Root Elements
-- `./spectra.config.ts`: Single source of truth for runtime configurations (Base URL, Appium devices, browser targets, timeouts).
-- `./.testspectra/`: Local test project cache, runtime metadata, auto-generated master TSConfig (`.testspectra/tsconfig.json`), platform sub-configs (`.testspectra/tsconfig/`), and universal ambient types (`.testspectra/types/`). Global binaries and drivers are managed at `~/.testspectra/drivers/`.
-- `./nx.json`: Nx target defaults with execution caching and inputs.
-- `./pnpm-workspace.yaml`: Monorepo package glob definitions.
-- `./tsconfig.json`: Solution-style TypeScript orchestrator referencing `./.testspectra/tsconfig.json`.
-
-### Centralized Shared Testing Library (`./__SHARED_TESTING_REL_PATH__`)
-Provides cross-feature reusable test entities with **100% zero-import global resolution**:
-- `page-objects/`: Shared Page Object models (e.g. NavigationBar, AppHeader).
-- `support/steps/`: Cross-feature business step flows (e.g. `Step.loginAsAdmin()`).
-- `support/actions/`: Custom atomic actions (e.g. `Spectra.dismissBanner()`).
-- `fixtures/`: Common test data and environment configurations (e.g. `Fixture.appConfig`).
-
-### Distributed Feature E2E Modules (__FEATURE_COUNT__ Features)
-__FEATURE_MODULES_SECTION__
-
----
-
-## 2. Zero-Import Consumption Flow & Mechanics
-
-TestSpectra completely eliminates boilerplate `import` statements across all test specs, steps, and page objects.
-
-### How It Works:
-1. **Centralized Ambient Aggregation**:  
-   TestSpectra Language Service Plugin & CLI automatically scan:
-   - **Local Feature Entities**: `<feature>/__E2E_FOLDER_NAME__/page-objects/`, `<feature>/__E2E_FOLDER_NAME__/support/steps/`, `<feature>/__E2E_FOLDER_NAME__/support/actions/`
-   - **Shared Library Entities**: `./__SHARED_TESTING_REL_PATH__/page-objects/`, `./__SHARED_TESTING_REL_PATH__/support/steps/`, `./__SHARED_TESTING_REL_PATH__/support/actions/`, `./__SHARED_TESTING_REL_PATH__/fixtures/`
-2. **Ambient Typing Generation**:  
-   These are compiled into `.testspectra/types/web.d.ts`, `android.d.ts`, `ios.d.ts`, `fixtures.d.ts`.
-3. **Instant IDE Autocomplete & Zero Clutter**:  
-   Specs consume both local feature objects and shared library utilities globally.
-
-### Code Example:
-```typescript
-// packages/features/auth/e2e/specs/Auth/TC-AUTH-01/web.test.ts
-// 🌟 NOTICE: 100% Zero-Import & Flat Execution! (No import statement, no describe wrapper)
-
-it("should navigate via shared header and login with local POM", async () => {
-  // 1. Consumed from Shared Testing Library (__SHARED_TESTING_REL_PATH__/page-objects/NavigationBar)
-  await NavigationBar.goToLogin();
-
-  // 2. Consumed from Shared Testing Library (__SHARED_TESTING_REL_PATH__/support/steps/loginAsAdmin)
-  await Step.loginAsAdmin();
-
-  // 3. Consumed from Local Feature POM (page-objects/LoginPage)
-  await LoginPage.flashAlert.shouldBeVisible();
-  await LoginPage.flashAlert.shouldContainText("Welcome");
-
-  // 4. Consumed from Shared Testing Library Custom Action (__SHARED_TESTING_REL_PATH__/support/actions/dismissBanner)
-  await Spectra.dismissBanner();
-});
-```
-
----
-
-## 3. How to Run Tests
-
-You can execute tests either from the **Monorepo Root via Nx** or directly inside each **Feature Directory via CLI**:
-
-### Option A: From Root Monorepo via Nx (Recommended for CI & Team Workflows)
-
-```bash
-# 1. Run E2E for a SPECIFIC feature module (e.g. auth)
-pnpm nx run auth-__E2E_FOLDER_NAME__:e2e
-
-# 2. Run E2E for a specific feature on ANDROID or IOS
-pnpm nx run auth-__E2E_FOLDER_NAME__:e2e --configuration=android
-pnpm nx run auth-__E2E_FOLDER_NAME__:e2e --configuration=ios
-
-# 3. Run E2E for a specific feature in HEADLESS browser mode
-pnpm nx run auth-__E2E_FOLDER_NAME__:e2e --configuration=headless
-
-# 4. Run ALL feature E2E suites across the entire monorepo in parallel
-pnpm nx run-many -t e2e
-
-# 5. Run only E2E tests for features modified in current Git branch / PR
-pnpm nx affected -t e2e
-```
-
-### Option B: From Inside the Feature Directory (Direct CLI)
-
-```bash
-# Navigate to the feature e2e folder
-cd __SAMPLE_FEATURE_E2E_PATH__
-
-# Run all specs in this feature
-pnpm spectra run
-
-# Run a specific test case file
-pnpm spectra run specs/Auth/TC-AUTH-01/web.test.ts
-
-# Target Android device or emulator
-pnpm spectra run --target android
-
-# Run in headed / interactive browser mode
-pnpm spectra run --no-headless
-```
-
----
-
-## 4. Type Checking & Validation
-
-```bash
-# Type check all E2E projects via Nx
-pnpm nx run-many -t type-check
-
-# Or standard TypeScript project references build from root
-pnpm type-check
-# or: npx tsc -b
-```