@testspectra/cli 1.1.7 → 1.1.8-rc.2

package/dist/runner/bridge.js

@@ -4,23 +4,6 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-// npm/pnpm pack+extract doesn't reliably preserve the executable bit on
-// non-`bin`-field binaries — testspectra-runner has been observed installed
-// as 0644 from a tarball that was 0755 at publish time. Defensive chmod so
-// every consumer works regardless of how it arrived on disk.
-function ensureExecutable(binPath) {
-    if (process.platform === 'win32')
-        return;
-    try {
-        const mode = fs.statSync(binPath).mode;
-        if ((mode & 0o111) === 0) {
-            fs.chmodSync(binPath, 0o755);
-        }
-    }
-    catch {
-        // best-effort — if this fails, the spawn below will surface the real error
-    }
-}
 export class RustCoreBridge {
     static resolveBinaryPath() {
         // 1. Look for precompiled release/debug binary in workspace target
@@ -40,7 +23,6 @@ export class RustCoreBridge {
         ];
         for (const p of candidatePaths) {
             if (fs.existsSync(p)) {
-                ensureExecutable(p);
                 return p;
             }
             if (fs.existsSync(`${p}.exe`)) {
@@ -62,7 +44,7 @@ export class RustCoreBridge {
             targetDevice: options.targetDevice,
             licenseKey: options.licenseKey,
             outputJsonPath: options.outputJsonPath,
-            spec: options.spec,
+            specs: options.specs,
             concurrency: options.concurrency,
             failedOnly: options.failedOnly,
             failedTarget: options.failedTarget,
@@ -80,6 +62,7 @@ export class RustCoreBridge {
             TEST_SPECTRA_DRIVER_CACHE: globalDriversDir,
             RUST_LOG: 'info',
         };
+        const runStartedAt = Date.now();
         return new Promise((resolve, reject) => {
             const child = spawn(binPath, [payload], {
                 env: runnerEnv,
@@ -97,6 +80,15 @@ export class RustCoreBridge {
                             level: 'INFO',
                             message: line,
                         });
+                        // In interactive terminals, the reporter above already renders this tag as part of
+                        // its live-updating spinner UI (`renderActiveSlots`), so echoing the raw tag too would
+                        // just duplicate/clutter that UI. But that live rendering is a no-op when stdout isn't
+                        // a real TTY (CI, or an external tool like the VS Code extension spawning this process
+                        // 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.
+                        if (!reporter.isInteractiveMode()) {
+                            console.log(line);
+                        }
                         continue;
                     }
                     try {
@@ -138,16 +130,37 @@ export class RustCoreBridge {
                 const str = data.toString();
                 // Ignore normal compilation progress
                 if (!str.includes('Compiling') && !str.includes('Checking') && !str.includes('Finished')) {
+                    const trimmed = str.trim();
                     reporter.addLog({
                         timestamp: new Date().toLocaleTimeString(),
                         level: 'DEBUG',
-                        message: str.trim(),
+                        message: trimmed,
                     });
+                    // Surface fatal runner errors (e.g. bootstrap failures like a missing APK) immediately —
+                    // previously these only landed in the JSON report's `logs[]`, so a failed run gave no
+                    // visible reason on the terminal.
+                    if (trimmed.startsWith('Error:')) {
+                        console.error(`\x1b[38;2;248;113;113m✖ ${trimmed}\x1b[0m`);
+                    }
                 }
             });
             child.on('close', (code) => {
                 let result = reporter.generateResult(code === 0 ? 'passed' : runStatus, runDuration);
+                // Only trust a pre-existing outputJsonPath when it was actually written during THIS run
+                // (mtime at/after runStartedAt) — NOT just when the process exited with code 0. The
+                // native runner writes its own complete report once the pipeline reaches the report
+                // stage, even for a run with failing tests (which still exits non-zero); but if it bails
+                // before ever getting there (missing APK, driver bootstrap error, etc.) a stale file from
+                // an unrelated previous run may still be sitting at this path — trusting it purely based
+                // on exit code would silently report that old run's result instead of the real failure.
+                let isFresh = false;
                 if (options.outputJsonPath && fs.existsSync(options.outputJsonPath)) {
+                    try {
+                        isFresh = fs.statSync(options.outputJsonPath).mtimeMs >= runStartedAt;
+                    }
+                    catch { }
+                }
+                if (isFresh && options.outputJsonPath) {
                     try {
                         const raw = fs.readFileSync(options.outputJsonPath, 'utf-8');
                         const parsed = JSON.parse(raw);
@@ -161,7 +174,7 @@ export class RustCoreBridge {
                     }
                     catch { }
                 }
-                else if (options.outputJsonPath) {
+                if (options.outputJsonPath && !isFresh) {
                     const outDir = path.dirname(options.outputJsonPath);
                     if (!fs.existsSync(outDir)) {
                         fs.mkdirSync(outDir, { recursive: true });

package/dist/runner/reporter.d.ts

@@ -43,6 +43,8 @@ export declare class Reporter {
     private spinnerIndex;
     private spinnerTimer;
     constructor();
+    /** Whether this reporter is drawing the live-updating interactive terminal UI (real TTY, not CI/VS Code/test). */
+    isInteractiveMode(): boolean;
     private clearActiveSlots;
     private renderActiveSlots;
     private resolveTestCase;

package/dist/runner/reporter.js

@@ -19,6 +19,8 @@ function mapActionArgs(key, arr) {
             return { durationMs: arr[0] };
         case 'navigate':
             return { url: arr[0] };
+        case 'setCookies':
+            return { url: arr[0] };
         case 'setViewport':
             return { width: arr[0], height: arr[1] };
         case 'wait':
@@ -63,9 +65,11 @@ function mapAssertionArgs(key, arr) {
 function parseAndFormat(cmdText) {
     try {
         const payload = JSON.parse(cmdText);
-        const target = typeof payload.target === 'object' && payload.target !== null
-            ? payload.target.selector || payload.target.name || payload.target.target || payload.target
-            : payload.target;
+        // Passed through as-is (not pre-flattened to a bare string here) — `formatAction`/
+        // `formatAssertion` already do the same `.selector`/`.name`/`.target` fallback lookup
+        // themselves, and only the raw object retains `.parent` for a scoped (`element.get()`/
+        // `.getAll()`-chained) target, which they need to render the "within" phrasing.
+        const target = payload.target;
         if (payload.type === 'action') {
             return formatAction(payload.key, target, mapActionArgs(payload.key, payload.args || []));
         }
@@ -167,6 +171,10 @@ export class Reporter {
             }, 80);
         }
     }
+    /** Whether this reporter is drawing the live-updating interactive terminal UI (real TTY, not CI/VS Code/test). */
+    isInteractiveMode() {
+        return this.isInteractive;
+    }
     clearActiveSlots() {
         if (!this.isInteractive || this.lastRenderedLines === 0)
             return;

package/dist/utils/__tests__/api-server.test.d.ts

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

package/dist/utils/__tests__/api-server.test.js

@@ -0,0 +1,62 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { DemoApiServer } from '../api-server.js';
+describe('DemoApiServer self-hosted REST API (cli/src/utils/api-server.ts)', () => {
+    let server;
+    let port;
+    const base = () => `http://127.0.0.1:${port}`;
+    beforeAll(async () => {
+        server = new DemoApiServer(0);
+        const info = await server.start();
+        port = info.port;
+    });
+    afterAll(async () => {
+        await server?.stop();
+    });
+    it('GET /api/posts returns the self-hosted post list', async () => {
+        const res = await fetch(`${base()}/api/posts`);
+        expect(res.status).toBe(200);
+        const data = await res.json();
+        expect(Array.isArray(data)).toBe(true);
+        expect(data.length).toBeGreaterThan(0);
+        expect(data[0]).toHaveProperty('id');
+        expect(data[0]).toHaveProperty('title');
+    });
+    it('GET /api/users returns a user list with name/email', async () => {
+        const res = await fetch(`${base()}/api/users`);
+        expect(res.status).toBe(200);
+        const data = await res.json();
+        expect(Array.isArray(data)).toBe(true);
+        expect(data[0]).toHaveProperty('name');
+        expect(data[0]).toHaveProperty('email');
+    });
+    it('GET /api/todos/1 returns a single todo', async () => {
+        const res = await fetch(`${base()}/api/todos/1`);
+        expect(res.status).toBe(200);
+        const data = await res.json();
+        expect(data).toHaveProperty('id', 1);
+        expect(data).toHaveProperty('completed');
+    });
+    it('POST /api/posts creates a post with a numeric id (201)', async () => {
+        const res = await fetch(`${base()}/api/posts`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json; charset=UTF-8' },
+            body: JSON.stringify({ title: 'TestSpectra seeded post', body: 'Hook seeding', userId: 1 }),
+        });
+        expect(res.status).toBe(201);
+        const data = await res.json();
+        expect(typeof data.id).toBe('number');
+        expect(data.title).toBe('TestSpectra seeded post');
+    });
+    it('DELETE /api/posts/:id cleans up a seeded post (200)', async () => {
+        const res = await fetch(`${base()}/api/posts/123`, { method: 'DELETE' });
+        expect(res.status).toBe(200);
+    });
+    it('returns CORS headers on API responses', async () => {
+        const res = await fetch(`${base()}/api/posts`);
+        expect(res.headers.get('access-control-allow-origin')).toBe('*');
+    });
+    it('returns 404 for unknown API routes', async () => {
+        const res = await fetch(`${base()}/api/does-not-exist`);
+        expect(res.status).toBe(404);
+    });
+});

package/dist/utils/__tests__/demo-server.test.d.ts

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

package/dist/utils/__tests__/demo-server.test.js

@@ -0,0 +1,35 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { DemoServer } from '../demo-server.js';
+describe('DemoServer static web app (cli/src/utils/demo-server.ts)', () => {
+    let server;
+    let port;
+    const demoDistAvailable = DemoServer.resolveDemoDist() !== null;
+    const base = () => `http://127.0.0.1:${port}`;
+    beforeAll(async () => {
+        if (!demoDistAvailable)
+            return;
+        server = new DemoServer(0);
+        const info = await server.start();
+        port = info.port;
+    });
+    afterAll(async () => {
+        await server?.stop();
+    });
+    it.skipIf(!demoDistAvailable)('serves the demo web app index', async () => {
+        const res = await fetch(`${base()}/`);
+        expect(res.status).toBe(200);
+        expect(await res.text()).toContain('<div id="app"></div>');
+    });
+    it.skipIf(!demoDistAvailable)('falls back to index.html for SPA routes', async () => {
+        const res = await fetch(`${base()}/some/spa/route`);
+        expect(res.status).toBe(200);
+        expect(await res.text()).toContain('<div id="app"></div>');
+    });
+    it.skipIf(!demoDistAvailable)('does not serve /api/* (that is the separate DemoApiServer)', async () => {
+        const res = await fetch(`${base()}/api/posts`);
+        // /api/posts is not a static file, so the SPA fallback serves index.html (200) — never JSON.
+        const text = await res.text();
+        expect(text).toContain('<div id="app"></div>');
+        expect(() => JSON.parse(text)).toThrow();
+    });
+});

package/dist/utils/api-server.d.ts

@@ -0,0 +1,19 @@
+/** Port the self-hosted demo API server listens on (separate from the demo web app's 5173). */
+export declare const DEMO_API_PORT = 5200;
+/**
+ * Standalone self-hosted REST API server for the demo apps, kept separate from `DemoServer` (the
+ * static web app) so the API can run independently and either server can be swapped for a real
+ * backend in a project. Mirrors the small subset of jsonplaceholder.typicode.com shapes the demo's
+ * API sections exercise.
+ */
+export declare class DemoApiServer {
+    private server;
+    private port;
+    constructor(port?: number);
+    start(): Promise<{
+        url: string;
+        port: number;
+    }>;
+    private handleApi;
+    stop(): Promise<void>;
+}

package/dist/utils/api-server.js

@@ -0,0 +1,179 @@
+import http from 'http';
+/** Port the self-hosted demo API server listens on (separate from the demo web app's 5173). */
+export const DEMO_API_PORT = 5200;
+// Self-hosted dummy REST data for the demo app's API sections — keeps the ApiInterception and
+// ApiSeeding suites fully offline/deterministic instead of depending on an external service
+// (jsonplaceholder.typicode.com) whose reachability and latency were themselves a source of
+// flakiness. Mocked requests never reach these handlers (CDP/proxy intercepts them first); they
+// back the genuine passthrough cases (real network call recording, seed/cleanup hooks).
+const API_POSTS = [
+    {
+        userId: 1,
+        id: 1,
+        title: 'TestSpectra demo post one',
+        body: 'Self-hosted demo data served by the built-in TestSpectra API server.',
+    },
+    {
+        userId: 1,
+        id: 2,
+        title: 'TestSpectra demo post two',
+        body: 'No external network required — deterministic for CI and offline runs.',
+    },
+    {
+        userId: 2,
+        id: 3,
+        title: 'TestSpectra demo post three',
+        body: 'Intercept it with Spectra.intercept() or let it pass through untouched.',
+    },
+    {
+        userId: 2,
+        id: 4,
+        title: 'TestSpectra demo post four',
+        body: 'Served independently of the demo web app so either can run without the other.',
+    },
+];
+const API_USERS = [
+    { id: 1, name: 'Ada Lovelace', username: 'ada', email: 'ada@testspectra.dev' },
+    { id: 2, name: 'Alan Turing', username: 'alan', email: 'alan@testspectra.dev' },
+    { id: 3, name: 'Grace Hopper', username: 'grace', email: 'grace@testspectra.dev' },
+];
+const API_TODOS = [{ userId: 1, id: 1, title: 'Verify the self-hosted demo API responds', completed: false }];
+/** Fixed demo credentials — this is a deterministic offline sandbox, not a real auth system. */
+const DEMO_ACCOUNT = { email: 'demo@testspectra.dev', password: 'demo-password' };
+/**
+ * Issued session tokens, in-memory only (reset on server restart) — backs both `/api/login`'s
+ * `Set-Cookie` (web, read via `Spectra.browser.setCookies()`) and its JSON `token` field
+ * (Android, read by the app's own deep-link-triggered login and stored via its own secure
+ * storage — see docs/v2/features/authentication-and-session-seeding.md). `/api/me` looks a
+ * caller's cookie *or* `Authorization: Bearer <token>` up in this same map.
+ */
+const issuedSessions = new Map();
+/**
+ * Standalone self-hosted REST API server for the demo apps, kept separate from `DemoServer` (the
+ * static web app) so the API can run independently and either server can be swapped for a real
+ * backend in a project. Mirrors the small subset of jsonplaceholder.typicode.com shapes the demo's
+ * API sections exercise.
+ */
+export class DemoApiServer {
+    server = null;
+    port;
+    constructor(port = DEMO_API_PORT) {
+        this.port = port;
+    }
+    async start() {
+        return new Promise((resolve, reject) => {
+            this.server = http.createServer((req, res) => {
+                this.handleApi(req, res, req.url ? req.url.split('?')[0] : '/');
+            });
+            this.server.on('error', (err) => {
+                if (err.code === 'EADDRINUSE') {
+                    // Port already in use (e.g. user already running the API server)
+                    resolve({ url: `http://localhost:${this.port}`, port: this.port });
+                }
+                else {
+                    reject(err);
+                }
+            });
+            this.server.listen(this.port, '0.0.0.0', () => {
+                const addr = this.server?.address();
+                const actualPort = typeof addr === 'object' && addr !== null ? addr.port : this.port;
+                resolve({ url: `http://localhost:${actualPort}`, port: actualPort });
+            });
+        });
+    }
+    handleApi(req, res, pathname) {
+        // The demo web app (port 5173) calls this server (port 5200) cross-origin. A wildcard origin
+        // can't be combined with credentialed requests (Access-Control-Allow-Credentials), which
+        // /api/me below needs to receive the session cookie seeded via Spectra.browser.setCookies() —
+        // reflect the actual request Origin instead so both credentialed and simple requests work.
+        res.setHeader('Access-Control-Allow-Origin', req.headers.origin || '*');
+        res.setHeader('Access-Control-Allow-Credentials', 'true');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', '*');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        const sendJson = (status, payload) => {
+            // no-store: the demo app fetches these without a cache-buster, so a cached body would be
+            // served for later, differently-mocked requests to the same URL instead of reaching the
+            // mock proxy.
+            res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
+            res.end(JSON.stringify(payload));
+        };
+        if (pathname === '/api/login' && req.method === 'POST') {
+            const chunks = [];
+            req.on('data', (chunk) => chunks.push(chunk));
+            req.on('end', () => {
+                let payload = {};
+                try {
+                    payload = JSON.parse(Buffer.concat(chunks).toString('utf-8') || '{}');
+                }
+                catch { }
+                if (payload.email !== DEMO_ACCOUNT.email || payload.password !== DEMO_ACCOUNT.password) {
+                    sendJson(401, { error: 'Invalid credentials' });
+                    return;
+                }
+                const token = `demo-session-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+                issuedSessions.set(token, { email: DEMO_ACCOUNT.email });
+                // HttpOnly: JS on the page can't read this — only the browser's own network layer (and
+                // Spectra.browser.setCookies(), which operates at that same layer) can set/send it.
+                res.setHeader('Set-Cookie', `demo_session=${token}; Path=/; HttpOnly; SameSite=Lax`);
+                sendJson(200, { token, user: { email: DEMO_ACCOUNT.email } });
+            });
+            return;
+        }
+        if (pathname === '/api/me' && req.method === 'GET') {
+            const cookieHeader = req.headers.cookie || '';
+            const cookieToken = /(?:^|;\s*)demo_session=([^;]+)/.exec(cookieHeader)?.[1];
+            const bearerToken = /^Bearer\s+(.+)$/.exec(req.headers.authorization || '')?.[1];
+            const session = issuedSessions.get(cookieToken || '') || issuedSessions.get(bearerToken || '');
+            sendJson(200, session ? { authenticated: true, user: session } : { authenticated: false });
+            return;
+        }
+        if (pathname === '/api/posts' && req.method === 'GET') {
+            sendJson(200, API_POSTS);
+            return;
+        }
+        if (pathname === '/api/users' && req.method === 'GET') {
+            sendJson(200, API_USERS);
+            return;
+        }
+        if (pathname === '/api/todos/1' && req.method === 'GET') {
+            sendJson(200, API_TODOS[0]);
+            return;
+        }
+        if (pathname === '/api/posts' && req.method === 'POST') {
+            const chunks = [];
+            req.on('data', (chunk) => chunks.push(chunk));
+            req.on('end', () => {
+                let payload = {};
+                try {
+                    payload = JSON.parse(Buffer.concat(chunks).toString('utf-8') || '{}');
+                }
+                catch { }
+                sendJson(201, { ...payload, id: Date.now() });
+            });
+            return;
+        }
+        if (pathname.startsWith('/api/posts/') && req.method === 'DELETE') {
+            sendJson(200, {});
+            return;
+        }
+        sendJson(404, { error: 'Not Found' });
+    }
+    async stop() {
+        if (this.server) {
+            if (typeof this.server.closeAllConnections === 'function') {
+                this.server.closeAllConnections();
+            }
+            return new Promise((resolve) => {
+                this.server?.close(() => {
+                    this.server = null;
+                    resolve();
+                });
+            });
+        }
+    }
+}

package/dist/utils/demo-server.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Static file server for the demo web app bundle. Serves ONLY the web app — the self-hosted demo
+ * REST API lives in a separate `DemoApiServer` (`cli/src/utils/api-server.ts`, port 5200) so the
+ * two can run and be swapped independently.
+ */
 export declare class DemoServer {
     private server;
     private port;

package/dist/utils/demo-server.js

@@ -16,6 +16,11 @@ const MIME_TYPES = {
     '.woff2': 'font/woff2',
     '.ttf': 'font/ttf',
 };
+/**
+ * Static file server for the demo web app bundle. Serves ONLY the web app — the self-hosted demo
+ * REST API lives in a separate `DemoApiServer` (`cli/src/utils/api-server.ts`, port 5200) so the
+ * two can run and be swapped independently.
+ */
 export class DemoServer {
     server = null;
     port;
@@ -80,7 +85,9 @@ export class DemoServer {
                 }
             });
             this.server.listen(this.port, '0.0.0.0', () => {
-                resolve({ url: `http://localhost:${this.port}`, port: this.port });
+                const addr = this.server?.address();
+                const actualPort = typeof addr === 'object' && addr !== null ? addr.port : this.port;
+                resolve({ url: `http://localhost:${actualPort}`, port: actualPort });
             });
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/cli",
-  "version": "1.1.7",
+  "version": "1.1.8-rc.2",
   "description": "TestSpectra Zero-Config Cross-Platform Test Runner CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,6 +16,15 @@
     "spectra": "./bin/spectra.js",
     "testspectra": "./bin/spectra.js"
   },
+  "scripts": {
+    "build:rust": "node scripts/ensure-runner-binary.js",
+    "prebuild": "node scripts/ensure-runner-binary.js",
+    "build": "tsc && node scripts/copy-demo.js",
+    "watch": "tsc -w",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
   "files": [
     "dist",
     "bin",
@@ -25,31 +34,26 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@clack/prompts": "^1.7.0",
-    "chalk": "^5.3.0",
-    "commander": "^12.1.0",
-    "dotenv": "^16.4.5",
-    "ora": "^8.0.1",
-    "zod": "^3.23.8",
-    "@testspectra/matchers": "1.1.0"
+    "@clack/prompts": "catalog:",
+    "@testspectra/matchers": "^1.1.8-rc.2",
+    "@testspectra/react": "^1.1.8-rc.2",
+    "@testspectra/skills": "^1.1.8-rc.2",
+    "chalk": "catalog:",
+    "commander": "catalog:",
+    "dotenv": "catalog:",
+    "ora": "catalog:",
+    "typescript": "catalog:",
+    "yaml": "catalog:",
+    "zod": "catalog:"
   },
   "devDependencies": {
-    "@types/node": "^20.14.0",
-    "@wdio/globals": "^9.24.0",
-    "@wdio/mocha-framework": "^9.24.0",
-    "@wdio/types": "^9.24.0",
-    "esbuild": "^0.28.2",
-    "typescript": "^5.6.3",
-    "vitest": "^2.1.8"
+    "@types/node": "catalog:",
+    "@wdio/globals": "catalog:",
+    "@wdio/mocha-framework": "catalog:",
+    "@wdio/types": "catalog:",
+    "esbuild": "catalog:",
+    "vitest": "catalog:"
   },
   "type": "module",
-  "license": "SEE LICENSE IN LICENSE.md",
-  "scripts": {
-    "build:rust": "node scripts/ensure-runner-binary.js",
-    "prebuild": "node scripts/ensure-runner-binary.js",
-    "build": "tsc && node scripts/copy-demo.js",
-    "watch": "tsc -w",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  }
-}
+  "license": "SEE LICENSE IN LICENSE.md"
+}

package/templates/default/CLAUDE.md

@@ -1,11 +1,16 @@
-# CLAUDE.md - TestSpectra Framework Conventions
-
-## Commands
-- Run all Web tests: `pnpm test:web` (or `spectra run -t web`)
-- Run all Mobile tests: `pnpm test:mobile` (or `spectra run -t mobile`)
-- Run Android tests: `pnpm test:android` (or `spectra run -t android`)
-- Run iOS tests: `pnpm test:ios` (or `spectra run -t ios`)
-- Run specific spec: `spectra run "specs/Playground/TC-0001-form-controls/mobile.test.ts" -t mobile`
-- Type checking: `pnpm type-check` (or `tsc -b`)
-- Preflight doctor: `pnpm doctor` (or `spectra doctor`)
-- Sync ambient types: `pnpm sync-types`
+# CLAUDE.md - TestSpectra Framework Conventions
+
+## Commands
+- Run all Web tests: `pnpm test:web` (or `spectra run -t web`)
+- Run all Mobile tests: `pnpm test:mobile` (or `spectra run -t mobile`)
+- Run Android tests: `pnpm test:android` (or `spectra run -t android`)
+- Run iOS tests: `pnpm test:ios` (or `spectra run -t ios`)
+- Run specific spec: `spectra run "specs/Playground/TC-0001-form-controls/mobile.test.ts" -t mobile`
+- Type checking: `pnpm type-check` (or `tsc -b`)
+- Preflight doctor: `pnpm doctor` (or `spectra doctor`)
+- Sync ambient types: `pnpm sync-types`
+
+## Element Selectors
+- `~name` → **accessibility id** (Android `content-desc`, RN `accessibilityLabel`, web `aria-label`) — the portable default.
+- `#name` → **native id** (Android `resource-id`, RN `testID`, web CSS `id`).
+- Each prefix maps to exactly one attribute (no silent cross-matching). Prefer `~` for user-perceivable elements, `#` for stable test ids. See `docs/v2/cli/selectors.md`.

package/templates/default/global-hooks/after/mobile.hook.ts

@@ -1,3 +1,3 @@
-export default async function () {
-  // Global mobile teardown
-}
+export default async function () {
+  // Global mobile teardown
+}

package/templates/default/global-hooks/after/web.hook.ts

@@ -1,3 +1,3 @@
-export default async function () {
-  // Global web teardown
-}
+export default async function () {
+  // Global web teardown
+}

package/templates/default/global-hooks/before/mobile.hook.ts

@@ -1,3 +1,3 @@
-export default async function () {
-  // Global mobile initialization
-}
+export default async function () {
+  // Global mobile initialization
+}

package/templates/default/global-hooks/before/web.hook.ts

@@ -1,3 +1,3 @@
-export default async function () {
-  // Global web initialization
-}
+export default async function () {
+  // Global web initialization
+}

package/templates/default/package.json

@@ -17,8 +17,8 @@
     "postinstall": "spectra sync-types"
   },
   "devDependencies": {
-    "@testspectra/cli": "link:../..",
-    "@testspectra/matchers": "link:../../../tools/matchers",
+    "@testspectra/cli": "^1.1.8-rc.2",
+    "@testspectra/matchers": "^1.1.8-rc.2",
     "@types/node": "^20.14.0",
     "@wdio/cli": "^9.2.8",
     "@wdio/local-runner": "^9.2.8",
@@ -29,4 +29,4 @@
     "webdriverio": "^9.2.8",
     "typescript": "^5.4.5"
   }
-}
+}

package/templates/default/page-objects/AuthPage/mobile.ts

@@ -0,0 +1,5 @@
+class AuthPage {
+  get statusBadge() { return Spectra.get("~auth-status-badge"); }
+}
+
+export default new AuthPage();