@testspectra/cli 1.2.23 → 1.3.0

package/dist/commands/diagnose.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `spectra diagnose --spec <id>`: tells a timing failure from a real one. It runs the spec; on a
+ * failure it reruns it with a wait after one step at a time (`TESTSPECTRA_DELAY_STEPS`), closest to
+ * the failure first. The answer names the step the test must wait after, for the state the app
+ * reaches there: a `should*` assertion, never a sleep.
+ */
+export interface DiagnoseOptions {
+    spec?: string;
+    delay?: string;
+    target?: string;
+}
+export declare function diagnoseCommand(options: DiagnoseOptions): Promise<void>;

package/dist/commands/diagnose.js

@@ -0,0 +1,95 @@
+/**
+ * `spectra diagnose --spec <id>`: tells a timing failure from a real one. It runs the spec; on a
+ * failure it reruns it with a wait after one step at a time (`TESTSPECTRA_DELAY_STEPS`), closest to
+ * the failure first. The answer names the step the test must wait after, for the state the app
+ * reaches there: a `should*` assertion, never a sleep.
+ */
+import { spawnSync } from 'node:child_process';
+function describeTarget(target) {
+    if (target === undefined || target === null)
+        return '';
+    if (typeof target === 'string')
+        return target;
+    const scoped = target;
+    return scoped.parent ? `${scoped.selector} within ${describeTarget(scoped.parent)}` : String(scoped.selector ?? '');
+}
+function runOnce(spec, target, delayMs, delaySteps) {
+    const args = [process.argv[1] ?? '', 'run', '--spec', spec, '--target', target, '--no-video'];
+    if (delayMs > 0)
+        args.push('--delay', String(delayMs));
+    const result = spawnSync(process.argv[0] ?? 'node', args, {
+        encoding: 'utf8',
+        env: { ...process.env, ...(delaySteps ? { TESTSPECTRA_DELAY_STEPS: delaySteps } : {}), CI: '1' },
+        maxBuffer: 256 * 1024 * 1024,
+    });
+    const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.replace(/\x1b\[[0-9;]*m/g, '');
+    const steps = new Map();
+    let error = null;
+    for (const line of output.split('\n')) {
+        const step = /^\[TESTSPECTRA_STEP_(?:PASS|FAIL)\] (\{.*\}) \(\d+ms\)$/.exec(line.trim());
+        if (step) {
+            try {
+                const payload = JSON.parse(step[1] ?? '{}');
+                // What the step acted on, as the page saw it (`<button aria-label="Close dialog">`), else its selector.
+                const target = payload.resolved ?? describeTarget(payload.target);
+                if (typeof payload.step === 'number')
+                    steps.set(payload.step, `${payload.key} ${target}`.trim());
+            }
+            catch { }
+        }
+        if (!error && line.startsWith('[TESTSPECTRA_TEST_ERROR]'))
+            error = line.replace('[TESTSPECTRA_TEST_ERROR]', '').trim();
+    }
+    const passed = /\[TESTSPECTRA_TEST_PASS\]/.test(output) && !/\[TESTSPECTRA_TEST_FAIL\]/.test(output);
+    return { passed, steps, error };
+}
+export async function diagnoseCommand(options) {
+    const spec = options.spec;
+    if (!spec) {
+        console.error('spectra diagnose needs --spec <id>');
+        process.exitCode = 1;
+        return;
+    }
+    const target = options.target ?? 'web';
+    const delay = Number(options.delay ?? 1000);
+    const say = (text) => console.log(`[diagnose] ${text}`);
+    const label = (outcome, step) => outcome.steps.get(step) ?? `step ${step}`;
+    say(`running ${spec} as is…`);
+    const plain = runOnce(spec, target, 0);
+    if (plain.passed) {
+        say('passes without a delay: nothing to diagnose (run it a few times if it fails only sometimes).');
+        return;
+    }
+    say(`fails: ${plain.error ?? 'see its output'}`);
+    const failing = Math.max(0, ...plain.steps.keys());
+    if (failing < 2) {
+        say('fails before its second step: not a timing failure between steps.');
+        process.exitCode = 1;
+        return;
+    }
+    // A delay after every step also outwaits the short states a spec checks on purpose ("Checking
+    // availability…"), so the steps are tried one at a time, closest to the failure first.
+    const earliest = Math.max(1, failing - 10);
+    say(`last step before the failure: #${failing} ${label(plain, failing)}. Trying a ${delay}ms wait after one step at a time…`);
+    for (let step = failing - 1; step >= earliest; step -= 1) {
+        const outcome = runOnce(spec, target, delay, String(step));
+        say(`  wait after #${step} ${label(plain, step)}: ${outcome.passed ? 'passes' : 'fails'}`);
+        if (outcome.passed) {
+            say(`the test needs time after step #${step}: ${label(plain, step)}`);
+            if (plain.steps.get(step + 1))
+                say(`before step #${step + 1}: ${label(plain, step + 1)}`);
+            say('wait there for the state the app reaches (a pending check ending, a submit settling, a dialog closing) ' +
+                'with a should* assertion — never a sleep.');
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const range = runOnce(spec, target, delay, `${earliest}-${failing - 1}`);
+    if (range.passed) {
+        say(`no single wait is enough, but waits after steps #${earliest}-#${failing - 1} are: more than one step races there.`);
+    }
+    else {
+        say(`waits before the failing step do not help: not a timing failure. Read the failure context of: spectra run --spec ${spec}`);
+    }
+    process.exitCode = 1;
+}

package/dist/commands/run.js

@@ -8,6 +8,7 @@ import { TypeGenerator } from '../types/generator.js';
 import { DemoServer, DEFAULT_DEMO_PORT } from '../utils/demo-server.js';
 import { DemoApiServer } from '../utils/api-server.js';
 import { DevServerManager } from '../utils/dev-server-manager.js';
+import { claimRun, concurrentRunWarning, findActiveRun } from '../utils/run-lock.js';
 import { DemoStateManager } from '../utils/demo-state.js';
 function renderSummaryCard(options) {
     const width = 64;
@@ -286,6 +287,12 @@ export async function runCommand(specPaths, options = {}) {
             console.log('\x1b[36m[TestSpectra Grid]\x1b[0m Multi-device grid enabled (auto-detecting connected devices)');
         }
         console.log(`\x1b[36m[TestSpectra]\x1b[0m Base URL: \x1b[33m${config.webConfig.baseUrl}\x1b[0m\n`);
+        if (platform === 'web' && config.webConfig.baseUrl) {
+            const active = findActiveRun(config.webConfig.baseUrl);
+            if (active)
+                console.log(concurrentRunWarning(active));
+            claimRun(config.webConfig.baseUrl);
+        }
         const reporter = new Reporter();
         const targetDevice = options.devices || options.device || (options.allDevices || options.multiDevice ? 'auto' : undefined);
         const result = await RustCoreBridge.run({

package/dist/config/schema.d.ts

@@ -142,6 +142,14 @@ export interface WebConfig {
      * @default "5000"
      */
     implicitWait: string;
+    /**
+     * What a test case inherits from the one before it in the same worker.
+     * - `'suite'` (default): one browser session per batch, so a suite `before` hook can log in once;
+     *   cookies, localStorage and sessionStorage carry over, and the runner names what carried over.
+     * - `'testcase'`: each case starts with empty cookies and storage.
+     * @default "suite"
+     */
+    isolation?: 'suite' | 'testcase';
     /**
      * Delay between consecutive actions and commands in milliseconds (slow motion).
      * @default 0

package/dist/index.js

@@ -4,6 +4,7 @@ import { demoCommand } from './commands/demo.js';
 import { DEFAULT_DEMO_PORT } from './utils/demo-server.js';
 import { devicesCommand } from './commands/devices.js';
 import { doctorCommand } from './commands/doctor.js';
+import { diagnoseCommand } from './commands/diagnose.js';
 import { initCommand } from './commands/init.js';
 import { installCommand } from './commands/install.js';
 import { runCommand } from './commands/run.js';
@@ -87,6 +88,13 @@ Examples:
         .option('--strict', 'Treat warnings as errors and exit with code 1')
         .option('--json', 'Output diagnostic results as JSON')
         .action(lintCommand);
+    program
+        .command('diagnose')
+        .description('Tell a timing failure from a real one: rerun a failing spec with a step delay and bisect the step it must wait after')
+        .option('-s, --spec <path>', 'Spec to diagnose')
+        .option('-t, --target <target>', 'Target platform', 'web')
+        .option('--delay <ms>', 'Wait to try after a step', '1000')
+        .action(diagnoseCommand);
     program
         .command('doctor')
         .description('Verify local environment prerequisites (Bun, Git, ADB, Chrome, Spectra Android Agent, workspace packages)')

package/dist/runner/bridge.js

@@ -165,7 +165,16 @@ export class RustCoreBridge {
                         // via a pipe) — in that case this raw line is the *only* live signal a wrapping process
                         // can see, so it must still reach stdout verbatim.
                         // Always forward inspector websocket URL so IDE tools can attach directly.
-                        if (line.startsWith('[TESTSPECTRA_DEBUG_INSPECTOR]') || !reporter.isInteractiveMode()) {
+                        // Network entries are one JSON line per request: in a plain log they bury the steps
+                        // (an agent reading the tail sees only them). They always reach network-resources.json;
+                        // a wrapper that streams them (the VS Code extension) asks with TESTSPECTRA_STREAM_NETWORK=1.
+                        const isNetwork = line.startsWith('[TESTSPECTRA_NETWORK]');
+                        const streamNetwork = process.env.TESTSPECTRA_STREAM_NETWORK === '1';
+                        // Warnings name a cause (an input storm, a busy page, a mock that matched nothing): shown in every mode.
+                        const isWarning = line.startsWith('[TESTSPECTRA_WARNING]');
+                        if (line.startsWith('[TESTSPECTRA_DEBUG_INSPECTOR]') ||
+                            isWarning ||
+                            (!reporter.isInteractiveMode() && (!isNetwork || streamNetwork))) {
                             console.log(line);
                         }
                         continue;

package/dist/utils/run-lock.d.ts

@@ -0,0 +1,18 @@
+/**
+ * One run per server: two `spectra run`s against the same base URL share its data (one resets the
+ * mock while the other is mid-test) and fail in ways neither run explains. Each run records itself
+ * in a lock file named after its base URL; a second run warns, naming the first.
+ */
+interface LockInfo {
+    pid: number;
+    cwd: string;
+    startedAt: string;
+    baseUrl: string;
+}
+/** The run already holding `baseUrl`, if one is still alive. */
+export declare function findActiveRun(baseUrl: string): LockInfo | null;
+/** Claims `baseUrl` for this run; the returned function releases it (also on exit). */
+export declare function claimRun(baseUrl: string): () => void;
+/** The warning a second run prints. */
+export declare function concurrentRunWarning(active: LockInfo): string;
+export {};

package/dist/utils/run-lock.js

@@ -0,0 +1,59 @@
+/**
+ * One run per server: two `spectra run`s against the same base URL share its data (one resets the
+ * mock while the other is mid-test) and fail in ways neither run explains. Each run records itself
+ * in a lock file named after its base URL; a second run warns, naming the first.
+ */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+function lockPath(baseUrl) {
+    const id = createHash('sha1').update(baseUrl.replace(/\/+$/, '').toLowerCase()).digest('hex').slice(0, 16);
+    return path.join(os.tmpdir(), 'testspectra-locks', `${id}.json`);
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/** The run already holding `baseUrl`, if one is still alive. */
+export function findActiveRun(baseUrl) {
+    try {
+        const info = JSON.parse(fs.readFileSync(lockPath(baseUrl), 'utf8'));
+        return info.pid !== process.pid && isAlive(info.pid) ? info : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Claims `baseUrl` for this run; the returned function releases it (also on exit). */
+export function claimRun(baseUrl) {
+    const file = lockPath(baseUrl);
+    const info = { pid: process.pid, cwd: process.cwd(), startedAt: new Date().toISOString(), baseUrl };
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(info));
+    }
+    catch {
+        return () => undefined;
+    }
+    const release = () => {
+        try {
+            const current = JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (current.pid === process.pid)
+                fs.unlinkSync(file);
+        }
+        catch { }
+    };
+    process.once('exit', release);
+    return release;
+}
+/** The warning a second run prints. */
+export function concurrentRunWarning(active) {
+    return (`[TESTSPECTRA_WARNING] ⚠ another spectra run (pid ${active.pid}, ${active.cwd}, since ${active.startedAt}) ` +
+        `is testing ${active.baseUrl}: runs sharing one server reset and change each other's data — run one at a time`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/cli",
-  "version": "1.2.23",
+  "version": "1.3.0",
   "description": "TestSpectra Cross-Platform Test Runner CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,11 +25,11 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@testspectra/matchers": "^1.2.23",
-    "@testspectra/react": "^1.2.23",
-    "@testspectra/react-native": "^1.2.23",
-    "@testspectra/reporter": "^1.2.23",
-    "@testspectra/skills": "^1.2.23",
+    "@testspectra/matchers": "^1.3.0",
+    "@testspectra/react": "^1.3.0",
+    "@testspectra/react-native": "^1.3.0",
+    "@testspectra/reporter": "^1.3.0",
+    "@testspectra/skills": "^1.3.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "cross-spawn": "^7.0.6",
@@ -40,9 +40,9 @@
     "zod": "^3.23.8"
   },
   "optionalDependencies": {
-    "@testspectra/cli-darwin-arm64": "1.2.23",
-    "@testspectra/cli-linux-x64": "1.2.23",
-    "@testspectra/cli-win32-x64": "1.2.23"
+    "@testspectra/cli-darwin-arm64": "1.3.0",
+    "@testspectra/cli-linux-x64": "1.3.0",
+    "@testspectra/cli-win32-x64": "1.3.0"
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6",

package/templates/default/package.json

@@ -17,9 +17,9 @@
     "postinstall": "spectra sync-types"
   },
   "devDependencies": {
-    "@testspectra/cli": "^1.2.23",
-    "@testspectra/matchers": "^1.2.23",
-    "@testspectra/plugin-demo": "^1.2.23",
+    "@testspectra/cli": "^1.3.0",
+    "@testspectra/matchers": "^1.3.0",
+    "@testspectra/plugin-demo": "^1.3.0",
     "@types/node": "^20.14.0",
     "@wdio/cli": "^9.2.8",
     "@wdio/local-runner": "^9.2.8",

package/templates/nx/package.json

@@ -12,8 +12,8 @@
     "postinstall": "spectra sync-types"
   },
   "devDependencies": {
-    "@testspectra/cli": "^1.2.23",
-    "@testspectra/matchers": "^1.2.23",
+    "@testspectra/cli": "^1.3.0",
+    "@testspectra/matchers": "^1.3.0",
     "@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.2.23",
-    "@testspectra/matchers": "^1.2.23",
-    "@testspectra/react": "^1.2.23",
+    "@testspectra/cli": "^1.3.0",
+    "@testspectra/matchers": "^1.3.0",
+    "@testspectra/react": "^1.3.0",
     "@types/node": "^20.14.0",
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",

package/templates/react-native-component/package.json

@@ -12,9 +12,9 @@
     "postinstall": "spectra sync-types"
   },
   "devDependencies": {
-    "@testspectra/cli": "^1.2.23",
-    "@testspectra/matchers": "^1.2.23",
-    "@testspectra/react-native": "^1.2.23",
+    "@testspectra/cli": "^1.3.0",
+    "@testspectra/matchers": "^1.3.0",
+    "@testspectra/react-native": "^1.3.0",
     "@types/node": "^20.14.0",
     "@types/react": "^18.3.12",
     "@types/react-native": "^0.73.0",