@testspectra/cli 1.1.8-rc.3 → 1.1.8-rc.31

package/dist/index.js

@@ -7,12 +7,13 @@ import { initCommand } from './commands/init.js';
 import { installCommand } from './commands/install.js';
 import { runCommand } from './commands/run.js';
 import { testCommand } from './commands/test.js';
-import { updateCommand } from './commands/update.js';
+import { upgradeCommand } from './commands/upgrade.js';
 import { watchCommand } from './commands/watch.js';
 import { syncTypesCommand } from './commands/sync-types.js';
 import { refactorCommand } from './commands/refactor.js';
 import { lintCommand } from './commands/lint.js';
 import { licenseCommand } from './commands/license.js';
+import { docsUpdateCommand } from './commands/docs.js';
 import { skillsInitCommand, skillsListCommand, skillsAddCommand, skillsUpdateCommand, skillsRemoveCommand, } from './commands/skills.js';
 export * from './config/schema.js';
 export * from './config/loader.js';
@@ -24,10 +25,10 @@ export * from './types/generator.js';
 export * from '@testspectra/matchers';
 export function createCliProgram() {
     const program = new Command();
-    program.name('spectra').description('TestSpectra Zero-Config Cross-Platform Test Runner CLI').version('1.0.0');
+    program.name('spectra').description('TestSpectra Cross-Platform Test Runner CLI').version('1.0.0');
     program
         .command('init')
-        .description('Initialize testspectra.config.json and project directories')
+        .description('Initialize spectra.config.ts and project directories')
         .option('-t, --template <template>', 'Project template: default, nx, react-component')
         .option('-f, --force', 'Overwrite existing configuration if present')
         .action(initCommand);
@@ -40,15 +41,16 @@ export function createCliProgram() {
     program
         .command('install [dependency]')
         .description('Install missing testing dependencies, browser drivers, and workspace packages')
-        .option('-f, --force', 'Force re-installation of dependencies')
-        .addHelpText('after', `
-Examples:
-  $ spectra install                 Install all missing required dependencies automatically
-  $ spectra install chrome          Install Google Chrome for Testing & matching Chromedriver
-  $ spectra install adb             Install Google Android SDK Platform Tools (ADB)
-  $ spectra install bun             Install Bun runtime
-  $ spectra install android-driver  Install Spectra Android Native Driver & WDIO Service
-  $ spectra install wdio            Install WebDriverIO core packages and matchers`)
+        .option('-f, --force', 'Remove existing artifacts and perform a clean reinstall of the dependency')
+        .addHelpText('after', `
+Examples:
+  $ spectra install                 Install all missing required dependencies automatically
+  $ spectra install chrome          Install Google Chrome for Testing & matching Chromedriver
+  $ spectra install adb             Install Google Android SDK Platform Tools (ADB)
+  $ spectra install bun             Install Bun runtime
+  $ spectra install android-agent   Install Spectra Android Native Agent (spectra-agent.jar)
+  $ spectra install android-agent -f  Clean reinstall Spectra Android Native Agent
+  $ spectra install packages        Install TestSpectra CLI, Matchers & Android Agent packages`)
         .action(installCommand);
     program
         .command('demo')
@@ -85,30 +87,41 @@ Examples:
         .action(lintCommand);
     program
         .command('doctor')
-        .description('Verify local environment prerequisites (ADB, Spectra Android Driver, Chrome, Bun)')
+        .description('Verify local environment prerequisites (Bun, Git, ADB, Chrome, Spectra Android Agent, workspace packages)')
         .option('-v, --verbose', 'Show full installation paths for all detected runtimes and packages')
+        .option('--scope <category>', 'Only check one category: core, web, mobile (default: all)')
+        .option('--only <keys>', 'Only check specific dependencies (comma-separated): bun, git, cli, chrome, matchers, adb, agent')
         .option('--fix', 'Attempt automatic fix / download of missing tools')
         .option('--json', 'Output diagnostic results as JSON')
         .action(doctorCommand);
     program
-        .command('update')
-        .description('Update @testspectra/cli and @testspectra/matchers to the latest version from npm')
+        .command('upgrade [packages...]')
+        .alias('update')
+        .description('Upgrade TestSpectra ecosystem packages and system drivers to the latest versions')
         .option('--check', 'Only check for available updates without installing')
-        .action(updateCommand);
+        .option('--packages-only', 'Only upgrade NPM packages in package.json')
+        .option('--drivers-only', 'Only upgrade system binaries and drivers (ADB, Agent, Chrome)')
+        .option('--json', 'Output the update check (packages + drivers) as JSON (implies --check, no changes applied)')
+        .addHelpText('after', `
+Examples:
+  $ spectra upgrade                                    Upgrade all packages and system drivers
+  $ spectra upgrade @testspectra/cli                   Upgrade only the CLI package
+  $ spectra upgrade @testspectra/cli @testspectra/matchers  Upgrade specific packages
+  $ spectra upgrade --check                            Check what is outdated (packages + drivers)`)
+        .action(upgradeCommand);
     program
         .command('devices')
-        .description('List connected Android/iOS devices and local browsers')
-        .option('-t, --target <target>', 'Filter scope: android, ios, web, all', 'all')
+        .description('List connected Android devices (ADB)')
         .option('--json', 'Output results as JSON')
         .action(devicesCommand);
     program
         .command('license [action] [key]')
         .description('Manage TestSpectra commercial license (activate, status, remove)')
         .option('--json', 'Output license details as JSON')
-        .addHelpText('after', `
-Examples:
-  $ spectra license activate <KEY>   Activate license key and auto-configure private driver registry
-  $ spectra license status           Display active license organization, plan, and expiration
+        .addHelpText('after', `
+Examples:
+  $ spectra license activate <KEY>   Activate license key and auto-configure private driver registry
+  $ spectra license status           Display active license organization, plan, and expiration
   $ spectra license remove           Remove locally activated license credentials`)
         .action(licenseCommand);
     const skills = program
@@ -147,11 +160,19 @@ Examples:
         .option('-w, --cwd <dir>', 'Custom workspace directory')
         .option('-a, --agent <ids>', 'One-off override: comma-separated agent(s) to target, bypassing the saved "init" selection (claude, opencode, kilo, agents, gemini)')
         .action(skillsRemoveCommand);
+    const docs = program.command('docs').description('Manage generated TestSpectra workspace documentation');
+    docs
+        .command('update')
+        .description('Regenerate ARCHITECTURE.md from the current workspace state, without re-running init')
+        .option('-w, --cwd <dir>', 'Custom workspace directory')
+        .action(docsUpdateCommand);
     program
         .command('run [paths...]')
         .description('Execute test suite or individual test case')
         .option('-s, --spec <path>', 'Spec file path to execute')
         .option('-t, --target <target>', 'Target platform: web, android, ios, common', 'web')
+        .option('--host <name>', 'Target specific named host defined in spectra.config.ts (webConfig.hosts)')
+        .option('--base-url <url>', 'Override webConfig.baseUrl')
         .option('-d, --device <device>', 'Target device name or UDID')
         .option('--all-devices', 'Distribute test execution across all connected devices')
         .option('--multi-device', 'Distribute test execution across all connected devices (alias for --all-devices)')
@@ -170,20 +191,29 @@ Examples:
         .action(runCommand);
     program
         .command('test')
-        .description('Run React component tests via @testspectra/react (bundled Vitest browser mode)')
+        .description('Run React component tests via @testspectra/react')
+        .option('-r, --runner <engine>', 'Component test runner engine: spectra (default, native CDP) or vitest (Playwright browser mode)', 'spectra')
         .option('-w, --cwd <dir>', 'Custom workspace directory')
         .option('-s, --spec <path>', 'Spec file path (or substring filter) to execute')
         .option('--headless', 'Run in headless mode (default)')
         .option('--no-headless', 'Run in headed mode')
         .option('--headed', 'Run the browser in visible GUI mode (alias for --no-headless)')
-        .option('--step-delay <ms>', 'Delay after each action/assertion in milliseconds (slow motion, for observing DOM transitions in --headed mode)')
+        .option('-d, --step-delay <ms>', 'Delay after each action/assertion in milliseconds (slow motion, for observing DOM transitions in --headed mode)')
         .option('--delay <ms>', 'Alias for --step-delay')
-        .option('-c, --concurrency <number>', 'Run spec files sequentially (1) or in parallel (>1, default). Browser mode has no numeric N-worker sizing like `spectra run`.')
-        .option('-o, --output <path>', 'Write a Vitest JSON test report to this path')
+        .option('-c, --concurrency <number>', 'Run spec files sequentially (1) or in parallel (>1, default).')
+        .option('-o, --output <path>', 'Write a JSON test report to this path')
         .action(testCommand);
     return program;
 }
 export async function runCli(args = process.argv) {
     const program = createCliProgram();
     await program.parseAsync(args);
+    // Commands whose stdout must stay machine-readable or is purely diagnostic never emit the
+    // interactive "update available" banner.
+    const silentCommands = ['doctor', 'install', 'upgrade', 'update'];
+    if (silentCommands.includes(program.args[0]))
+        return;
+    const { checkUpdateInBackground, displayUpdateNotificationIfNeeded } = await import('./utils/update-notifier.js');
+    checkUpdateInBackground();
+    displayUpdateNotificationIfNeeded();
 }

package/dist/linter/__tests__/component-test-imports.test.js

@@ -14,20 +14,20 @@ const __dirname = path.dirname(__filename);
  */
 describe('Component Test (.tsx) Import Exception', () => {
     const tempDir = path.join(__dirname, '__temp_tsx_imports__');
-    const specFrontmatter = `---
-id: TC-0200
-title: Sample component test
-priority: High
-caseType: Positive
-status: automated
-coverage:
-  web: automated
----
-
-# Sample component test
-
-## Test Steps
-1. Mount the component and assert it is visible.
+    const specFrontmatter = `---
+id: TC-0200
+title: Sample component test
+priority: High
+caseType: Positive
+status: automated
+coverage:
+  web: automated
+---
+
+# Sample component test
+
+## Test Steps
+1. Mount the component and assert it is visible.
 `;
     beforeEach(() => {
         fs.mkdirSync(tempDir, { recursive: true });
@@ -39,23 +39,23 @@ coverage:
         }
     });
     it('does not flag no-manual-import for ordinary component/library imports in .test.tsx', () => {
-        fs.writeFileSync(path.join(tempDir, 'web.test.tsx'), `import { Button } from '../../src/components/Button/Button.js';
-import React from 'react';
-
-it('Sample component test', async () => {
-  await Spectra.mount(<Button label="Save" />);
-});
+        fs.writeFileSync(path.join(tempDir, 'web.test.tsx'), `import { Button } from '../../src/components/Button/Button.js';
+import React from 'react';
+
+it('Sample component test', async () => {
+  await Spectra.mount(<Button label="Save" />);
+});
 `);
         const { diagnostics } = SpecLinter.validateSpecFile(path.join(tempDir, 'spec.md'));
         const importErrors = diagnostics.filter((d) => d.code === 'testspectra/no-manual-import');
         expect(importErrors).toHaveLength(0);
     });
     it('still flags no-manual-import when a .test.tsx import resolves into page-objects/', () => {
-        fs.writeFileSync(path.join(tempDir, 'web.test.tsx'), `import ButtonComponent from '../../page-objects/ButtonComponent/web.js';
-
-it('Sample component test', async () => {
-  await ButtonComponent.root.shouldBeVisible();
-});
+        fs.writeFileSync(path.join(tempDir, 'web.test.tsx'), `import ButtonComponent from '../../page-objects/ButtonComponent/web.js';
+
+it('Sample component test', async () => {
+  await ButtonComponent.root.shouldBeVisible();
+});
 `);
         const { diagnostics } = SpecLinter.validateSpecFile(path.join(tempDir, 'spec.md'));
         const importErrors = diagnostics.filter((d) => d.code === 'testspectra/no-manual-import');
@@ -63,50 +63,50 @@ it('Sample component test', async () => {
         expect(importErrors[0].message).toContain('page-objects');
     });
     it('still flags no-manual-import when a .test.tsx import resolves into support/steps/', () => {
-        fs.writeFileSync(path.join(tempDir, 'web.test.tsx'), `import verifyButtonState from '../../support/steps/verifyButtonState/web.step.js';
-
-it('Sample component test', async () => {
-  await verifyButtonState('Save', true);
-});
+        fs.writeFileSync(path.join(tempDir, 'web.test.tsx'), `import verifyButtonState from '../../support/steps/verifyButtonState/web.step.js';
+
+it('Sample component test', async () => {
+  await verifyButtonState('Save', true);
+});
 `);
         const { diagnostics } = SpecLinter.validateSpecFile(path.join(tempDir, 'spec.md'));
         const importErrors = diagnostics.filter((d) => d.code === 'testspectra/no-manual-import');
         expect(importErrors).toHaveLength(1);
     });
     it('still flags no-manual-import when a .test.tsx import resolves into fixtures/', () => {
-        fs.writeFileSync(path.join(tempDir, 'web.test.tsx'), `import users from '../../fixtures/users.json';
-
-it('Sample component test', async () => {
-  expect(users).toBeDefined();
-});
+        fs.writeFileSync(path.join(tempDir, 'web.test.tsx'), `import users from '../../fixtures/users.json';
+
+it('Sample component test', async () => {
+  expect(users).toBeDefined();
+});
 `);
         const { diagnostics } = SpecLinter.validateSpecFile(path.join(tempDir, 'spec.md'));
         const importErrors = diagnostics.filter((d) => d.code === 'testspectra/no-manual-import');
         expect(importErrors).toHaveLength(1);
     });
     it('still enforces single-it-required and no-describe-block in .test.tsx files', () => {
-        fs.writeFileSync(path.join(tempDir, 'web.test.tsx'), `import { Button } from '../../src/components/Button/Button.js';
-
-describe('Button', () => {
-  it('Sample component test', async () => {
-    await Spectra.mount(<Button label="Save" />);
-  });
-
-  it('Another test', async () => {
-    await Spectra.mount(<Button label="Cancel" />);
-  });
-});
+        fs.writeFileSync(path.join(tempDir, 'web.test.tsx'), `import { Button } from '../../src/components/Button/Button.js';
+
+describe('Button', () => {
+  it('Sample component test', async () => {
+    await Spectra.mount(<Button label="Save" />);
+  });
+
+  it('Another test', async () => {
+    await Spectra.mount(<Button label="Cancel" />);
+  });
+});
 `);
         const { diagnostics } = SpecLinter.validateSpecFile(path.join(tempDir, 'spec.md'));
         expect(diagnostics.some((d) => d.code === 'testspectra/no-describe-block')).toBe(true);
         expect(diagnostics.some((d) => d.code === 'testspectra/single-it-required')).toBe(true);
     });
     it('still forbids all imports (unchanged behavior) in plain .test.ts E2E specs', () => {
-        fs.writeFileSync(path.join(tempDir, 'web.test.ts'), `import { LoginPage } from '../../page-objects/LoginPage/web.js';
-
-it('Sample component test', async () => {
-  await LoginPage.submitButton.click();
-});
+        fs.writeFileSync(path.join(tempDir, 'web.test.ts'), `import { LoginPage } from '../../page-objects/LoginPage/web.js';
+
+it('Sample component test', async () => {
+  await LoginPage.submitButton.click();
+});
 `);
         const { diagnostics } = SpecLinter.validateSpecFile(path.join(tempDir, 'spec.md'));
         const importErrors = diagnostics.filter((d) => d.code === 'testspectra/no-manual-import');

package/dist/linter/__tests__/shared-lib-boundary.test.js

@@ -17,16 +17,16 @@ describe('Shared Library Boundary (testspectra/no-specs-in-shared-lib)', () => {
         }
     });
     describe('findSharedLibraryRoots()', () => {
-        it('discovers parent folders of project.json files containing both scope:shared and type:shared', () => {
+        it('discovers parent folders of project.json files containing testspectra:shared', () => {
             const sharedDir1 = path.join(tempDir, 'shared', 'testing');
             const sharedDir2 = path.join(tempDir, 'libs', 'common-helpers');
             const nonSharedDir = path.join(tempDir, 'packages', 'playground', 'e2e');
             fs.mkdirSync(sharedDir1, { recursive: true });
             fs.mkdirSync(sharedDir2, { recursive: true });
             fs.mkdirSync(nonSharedDir, { recursive: true });
-            fs.writeFileSync(path.join(sharedDir1, 'project.json'), JSON.stringify({ name: 'shared-testing', tags: ['scope:shared', 'type:shared'] }));
-            fs.writeFileSync(path.join(sharedDir2, 'project.json'), JSON.stringify({ name: 'common-helpers', tags: ['scope:shared', 'type:shared'] }));
-            fs.writeFileSync(path.join(nonSharedDir, 'project.json'), JSON.stringify({ name: 'playground-e2e', tags: ['scope:playground', 'type:e2e'] }));
+            fs.writeFileSync(path.join(sharedDir1, 'project.json'), JSON.stringify({ name: 'shared-testing', tags: ['testspectra:shared'] }));
+            fs.writeFileSync(path.join(sharedDir2, 'project.json'), JSON.stringify({ name: 'common-helpers', tags: ['testspectra:shared'] }));
+            fs.writeFileSync(path.join(nonSharedDir, 'project.json'), JSON.stringify({ name: 'playground-e2e', tags: ['testspectra:e2e', 'testspectra:scope:playground'] }));
             const roots = findSharedLibraryRoots(tempDir);
             expect(roots).toHaveLength(2);
             expect(roots).toContain(sharedDir1);
@@ -35,12 +35,12 @@ describe('Shared Library Boundary (testspectra/no-specs-in-shared-lib)', () => {
         });
     });
     describe('isInsideSharedLibrary()', () => {
-        it('returns true for files inside a project tagged with scope:shared or type:shared in project.json', () => {
+        it('returns true for files inside a project tagged with testspectra:shared in project.json', () => {
             const sharedDir = path.join(tempDir, 'shared', 'testing');
             fs.mkdirSync(sharedDir, { recursive: true });
             fs.writeFileSync(path.join(sharedDir, 'project.json'), JSON.stringify({
                 name: 'shared-testing',
-                tags: ['scope:shared', 'type:shared'],
+                tags: ['testspectra:shared'],
             }));
             const stepFile = path.join(sharedDir, 'support', 'steps', 'web.step.ts');
             const specFile = path.join(sharedDir, 'specs', 'TC-001', 'spec.md');
@@ -55,7 +55,7 @@ describe('Shared Library Boundary (testspectra/no-specs-in-shared-lib)', () => {
             fs.mkdirSync(customLibDir, { recursive: true });
             fs.writeFileSync(path.join(customLibDir, 'project.json'), JSON.stringify({
                 name: 'custom-common-lib',
-                tags: ['scope:shared', 'type:shared'],
+                tags: ['testspectra:shared'],
             }));
             const actionFile = path.join(customLibDir, 'support', 'actions', 'click.action.ts');
             expect(isInsideSharedLibrary(actionFile)).toBe(true);
@@ -65,7 +65,7 @@ describe('Shared Library Boundary (testspectra/no-specs-in-shared-lib)', () => {
             fs.mkdirSync(sharedAppDir, { recursive: true });
             fs.writeFileSync(path.join(sharedAppDir, 'project.json'), JSON.stringify({
                 name: 'shared-app',
-                tags: ['scope:shared-app', 'type:e2e'],
+                tags: ['testspectra:e2e', 'testspectra:scope:shared-app'],
             }));
             const specFile = path.join(sharedAppDir, 'specs', 'TC-001', 'spec.md');
             expect(isInsideSharedLibrary(specFile)).toBe(false);
@@ -75,7 +75,7 @@ describe('Shared Library Boundary (testspectra/no-specs-in-shared-lib)', () => {
             fs.mkdirSync(featureDir, { recursive: true });
             fs.writeFileSync(path.join(featureDir, 'project.json'), JSON.stringify({
                 name: 'playground-e2e',
-                tags: ['scope:playground', 'type:e2e'],
+                tags: ['testspectra:e2e', 'testspectra:scope:playground'],
             }));
             const specFile = path.join(featureDir, 'specs', 'TC-001', 'spec.md');
             expect(isInsideSharedLibrary(specFile)).toBe(false);
@@ -91,7 +91,7 @@ describe('Shared Library Boundary (testspectra/no-specs-in-shared-lib)', () => {
             fs.mkdirSync(sharedLibDir, { recursive: true });
             fs.writeFileSync(path.join(sharedLibDir, 'project.json'), JSON.stringify({
                 name: 'shared-testing',
-                tags: ['scope:shared', 'type:shared'],
+                tags: ['testspectra:shared'],
             }));
             const sharedSpecDir = path.join(sharedLibDir, 'specs', 'TC-error');
             fs.mkdirSync(sharedSpecDir, { recursive: true });
@@ -119,7 +119,7 @@ status: draft
             fs.mkdirSync(sharedLibDir, { recursive: true });
             fs.writeFileSync(path.join(sharedLibDir, 'project.json'), JSON.stringify({
                 name: 'shared-testing',
-                tags: ['scope:shared', 'type:shared'],
+                tags: ['testspectra:shared'],
             }));
             const sharedSuiteDir = path.join(sharedLibDir, 'support');
             fs.mkdirSync(sharedSuiteDir, { recursive: true });
@@ -141,7 +141,7 @@ status: active
             fs.mkdirSync(customLibDir, { recursive: true });
             fs.writeFileSync(path.join(customLibDir, 'project.json'), JSON.stringify({
                 name: 'my-testing-utils',
-                tags: ['scope:shared', 'type:shared'],
+                tags: ['testspectra:shared'],
             }));
             const specDir = path.join(customLibDir, 'specs', 'TC-custom');
             fs.mkdirSync(specDir, { recursive: true });
@@ -169,7 +169,7 @@ status: draft
             fs.mkdirSync(featureDir, { recursive: true });
             fs.writeFileSync(path.join(featureDir, 'project.json'), JSON.stringify({
                 name: 'playground-e2e',
-                tags: ['scope:playground', 'type:e2e'],
+                tags: ['testspectra:e2e', 'testspectra:scope:playground'],
             }));
             const featureSpecDir = path.join(featureDir, 'specs', 'TC-001');
             fs.mkdirSync(featureSpecDir, { recursive: true });
@@ -195,7 +195,7 @@ status: draft
             fs.mkdirSync(sharedE2eDir, { recursive: true });
             fs.writeFileSync(path.join(sharedE2eDir, 'project.json'), JSON.stringify({
                 name: 'shared-feature-e2e',
-                tags: ['scope:shared-feature', 'type:e2e'],
+                tags: ['testspectra:e2e', 'testspectra:scope:shared-feature'],
             }));
             const specDir = path.join(sharedE2eDir, 'specs', 'TC-001');
             fs.mkdirSync(specDir, { recursive: true });
@@ -241,7 +241,7 @@ status: draft
             fs.mkdirSync(sharedLibDir, { recursive: true });
             fs.writeFileSync(path.join(sharedLibDir, 'project.json'), JSON.stringify({
                 name: 'shared-testing',
-                tags: ['scope:shared', 'type:shared'],
+                tags: ['testspectra:shared'],
             }));
             const sharedDir1 = path.join(sharedLibDir, 'specs', 'TC-001');
             const sharedDir2 = path.join(sharedLibDir, 'specs', 'TC-002');