@testspectra/cli 1.1.0-rc.0 → 1.1.0-rc.1

package/dist/linter/schemas/suite.schema.d.ts

@@ -14,37 +14,37 @@ export declare const SuiteFrontmatterSchema: z.ZodEffects<z.ZodObject<{
     tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     id: string;
+    status?: "active" | "draft" | "deprecated" | undefined;
     title?: string | undefined;
-    status?: "draft" | "deprecated" | "active" | undefined;
-    tags?: string[] | undefined;
     name?: string | undefined;
+    tags?: string[] | undefined;
     description?: string | undefined;
     executionOrder?: number | undefined;
     parallel?: boolean | undefined;
 }, {
     id: string;
+    status?: "active" | "draft" | "deprecated" | undefined;
     title?: string | undefined;
-    status?: "draft" | "deprecated" | "active" | undefined;
-    tags?: string[] | undefined;
     name?: string | undefined;
+    tags?: string[] | undefined;
     description?: string | undefined;
     executionOrder?: number | undefined;
     parallel?: boolean | undefined;
 }>, {
     id: string;
+    status?: "active" | "draft" | "deprecated" | undefined;
     title?: string | undefined;
-    status?: "draft" | "deprecated" | "active" | undefined;
-    tags?: string[] | undefined;
     name?: string | undefined;
+    tags?: string[] | undefined;
     description?: string | undefined;
     executionOrder?: number | undefined;
     parallel?: boolean | undefined;
 }, {
     id: string;
+    status?: "active" | "draft" | "deprecated" | undefined;
     title?: string | undefined;
-    status?: "draft" | "deprecated" | "active" | undefined;
-    tags?: string[] | undefined;
     name?: string | undefined;
+    tags?: string[] | undefined;
     description?: string | undefined;
     executionOrder?: number | undefined;
     parallel?: boolean | undefined;

package/dist/linter/spec-linter.js

@@ -6,6 +6,25 @@ import { isInsideSharedLibrary } from './discovery.js';
 import { parseMarkdownFrontmatter } from './parser.js';
 import { SpecFrontmatterSchema, validateSpecSections } from './schemas/spec.schema.js';
 import { SuiteFrontmatterSchema, validateSuiteSections } from './schemas/suite.schema.js';
+/**
+ * Resolves an import specifier against the importing file's directory and checks whether it
+ * reaches into an ambient-global-backed directory (Page/Component Objects, Steps, Fixtures) —
+ * the only imports still forbidden in `.tsx` component test files. Everything else (React,
+ * component source under test, npm packages, test-utils helpers) is allowed in `.tsx`, unlike
+ * the fully zero-import `.ts` E2E spec contract.
+ *
+ * See docs/v2/features/component-testing/react/mount-convention.md §"Static Imports Are Allowed
+ * Here" for the rationale.
+ */
+function resolvesToAmbientGlobalDir(specifier, testFilePath) {
+    if (!specifier.startsWith('.'))
+        return false; // bare package specifiers (react, etc.) are fine
+    const resolved = path.normalize(path.join(path.dirname(testFilePath), specifier));
+    const segments = resolved.split(path.sep);
+    return (segments.includes('page-objects') ||
+        segments.includes('fixtures') ||
+        (segments.includes('support') && segments.includes('steps')));
+}
 export class SpecLinter {
     /**
      * Validates a single spec.md file.
@@ -105,11 +124,17 @@ export class SpecLinter {
             companionTestFiles = entries
                 .filter((e) => e.isFile() &&
                 (e.name.endsWith('.test.ts') ||
+                    e.name.endsWith('.test.tsx') ||
                     e.name.endsWith('.web.ts') ||
+                    e.name.endsWith('.web.tsx') ||
                     e.name.endsWith('.mobile.ts') ||
+                    e.name.endsWith('.mobile.tsx') ||
                     e.name.endsWith('.android.ts') ||
+                    e.name.endsWith('.android.tsx') ||
                     e.name.endsWith('.ios.ts') ||
-                    e.name.endsWith('.common.ts')))
+                    e.name.endsWith('.ios.tsx') ||
+                    e.name.endsWith('.common.ts') ||
+                    e.name.endsWith('.common.tsx')))
                 .map((e) => path.join(specDir, e.name));
         }
         catch { }
@@ -158,12 +183,22 @@ export class SpecLinter {
                     }
                 }
                 const symbols = extractSymbolsFromTestCode(testCode, testFilePath);
-                // testspectra/no-manual-import: Manual import statement detected (must be zero-import)
+                const isComponentTestFile = testFilePath.endsWith('.tsx');
+                // testspectra/no-manual-import: Manual import statement detected (must be zero-import).
+                // `.tsx` component test files (docs/v2/features/component-testing/react/) are exempt
+                // EXCEPT for imports that reach into ambient-global-backed directories (Page/Component
+                // Objects, Steps, Fixtures) — those stay forbidden so the ambient global is the single
+                // source of truth there too, exactly as in zero-import `.ts` E2E specs.
                 for (const imp of symbols.importStatements) {
+                    if (isComponentTestFile && !resolvesToAmbientGlobalDir(imp.specifier, testFilePath)) {
+                        continue;
+                    }
                     diagnostics.push({
                         code: 'testspectra/no-manual-import',
                         severity: 'error',
-                        message: 'Manual imports forbidden; all TestSpectra APIs, Page Objects, Steps, and Fixtures are ambient globals',
+                        message: isComponentTestFile
+                            ? `Manual import of "${imp.specifier}" is forbidden; Page/Component Objects, Steps, and Fixtures are ambient globals even in component test files`
+                            : 'Manual imports forbidden; all TestSpectra APIs, Page Objects, Steps, and Fixtures are ambient globals',
                         filePath: testFilePath,
                         line: imp.line,
                         column: imp.column,

package/dist/reporter/semantic-formatter.js

@@ -13,6 +13,17 @@ function extractTargetString(target) {
     }
     return String(target);
 }
+/** Renders a `ScopedSelector`'s `.parent` chain (produced by `element.get()`/`.getAll()`
+ * chaining) as `"parent" within "grandparent"`, nearest ancestor first — or null when the
+ * target isn't scoped. */
+function extractWithinChain(target) {
+    if (!target || typeof target !== 'object' || !target.parent)
+        return null;
+    const chain = [];
+    for (let p = target.parent; p; p = p.parent)
+        chain.push(p.selector);
+    return chain.join('" within "');
+}
 function formatElementTarget(target) {
     const sel = extractTargetString(target);
     if (!sel)
@@ -20,7 +31,8 @@ function formatElementTarget(target) {
     if (sel.startsWith('element "') || sel.startsWith('collection "')) {
         return sel;
     }
-    return `element "${sel}"`;
+    const within = extractWithinChain(target);
+    return within ? `element "${sel}" within "${within}"` : `element "${sel}"`;
 }
 function formatCollectionTarget(target) {
     const sel = extractTargetString(target);
@@ -29,7 +41,8 @@ function formatCollectionTarget(target) {
     if (sel.startsWith('collection "')) {
         return sel;
     }
-    return `collection "${sel}"`;
+    const within = extractWithinChain(target);
+    return within ? `collection "${sel}" within "${within}"` : `collection "${sel}"`;
 }
 /**
  * Transforms raw matcher assertions and element commands into grammatically correct English sentences.
@@ -83,6 +96,8 @@ export function formatAction(actionKey, target, args = {}) {
             return `Intercept ${args.method ?? '{method}'} "${args.url ?? '{url}'}" mock rule registered`;
         case 'clearCookies':
             return `Clear all browser cookies`;
+        case 'setCookies':
+            return `Set cookies for "${args.url ?? '{url}'}"`;
         case 'clearLocalStorage':
             return `Clear browser localStorage`;
         default:

package/dist/reporter/types.d.ts

@@ -1,2 +1,2 @@
-export type ActionKey = 'click' | 'doubleClick' | 'rightClick' | 'type' | 'clear' | 'select' | 'hover' | 'dragDrop' | 'scrollIntoView' | 'longPress' | 'waitForElement' | 'navigate' | 'back' | 'forward' | 'refresh' | 'setViewport' | 'wait' | 'pressKey' | 'scroll' | 'swipe' | 'intercept' | 'clearCookies' | 'clearLocalStorage';
+export type ActionKey = 'click' | 'doubleClick' | 'rightClick' | 'type' | 'clear' | 'select' | 'hover' | 'dragDrop' | 'scrollIntoView' | 'longPress' | 'waitForElement' | 'navigate' | 'back' | 'forward' | 'refresh' | 'setViewport' | 'wait' | 'pressKey' | 'scroll' | 'swipe' | 'intercept' | 'clearCookies' | 'setCookies' | 'clearLocalStorage';
 export type AssertionKey = 'be.visible' | 'not.be.visible' | 'exist' | 'not.exist' | 'be.clickable' | 'not.be.clickable' | 'be.enabled' | 'be.disabled' | 'be.checked' | 'not.be.checked' | 'be.selected' | 'not.be.selected' | 'be.focused' | 'not.be.focused' | 'have.text' | 'not.have.text' | 'contain.text' | 'not.contain.text' | 'have.value' | 'not.have.value' | 'contain.value' | 'not.contain.value' | 'have.attr' | 'not.have.attr' | 'have.class' | 'not.have.class' | 'have.css' | 'not.have.css' | 'have.length' | 'not.have.length' | 'have.length.greaterThan' | 'have.length.lessThan' | 'be.empty' | 'not.be.empty' | 'shouldHaveUrl' | 'shouldContainUrl' | 'shouldHaveTitle' | 'shouldContainTitle' | 'shouldBeLoaded' | 'shouldBePageLoaded' | 'shouldHaveNoConsoleErrors' | 'have.url' | 'contain.url' | 'have.title' | 'contain.title' | 'be.loaded' | 'be.pageLoaded' | 'have.noConsoleErrors';

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 || []));
         }

package/dist/utils/api-server.js

@@ -38,6 +38,16 @@ const API_USERS = [
     { 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
@@ -72,7 +82,12 @@ export class DemoApiServer {
         });
     }
     handleApi(req, res, pathname) {
-        res.setHeader('Access-Control-Allow-Origin', '*');
+        // 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') {
@@ -87,6 +102,36 @@ export class DemoApiServer {
             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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/cli",
-  "version": "1.1.0-rc.0",
+  "version": "1.1.0-rc.1",
   "description": "TestSpectra Zero-Config Cross-Platform Test Runner CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -35,8 +35,9 @@
   ],
   "dependencies": {
     "@clack/prompts": "catalog:",
-    "@testspectra/matchers": "^1.1.0-rc.0",
-    "@testspectra/skills": "^1.1.0-rc.0",
+    "@testspectra/matchers": "^1.1.0-rc.1",
+    "@testspectra/react": "workspace:*",
+    "@testspectra/skills": "^1.1.0-rc.1",
     "chalk": "catalog:",
     "commander": "catalog:",
     "dotenv": "catalog:",

package/templates/default/package.json

@@ -17,8 +17,8 @@
     "postinstall": "spectra sync-types"
   },
   "devDependencies": {
-    "@testspectra/cli": "^1.1.0-rc.0",
-    "@testspectra/matchers": "^1.1.0-rc.0",
+    "@testspectra/cli": "^1.1.0-rc.1",
+    "@testspectra/matchers": "^1.1.0-rc.1",
     "@types/node": "^20.14.0",
     "@wdio/cli": "^9.2.8",
     "@wdio/local-runner": "^9.2.8",

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();

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

@@ -0,0 +1,10 @@
+class AuthPage {
+  get checkStatusButton() { return Spectra.get("#check-auth-status-btn"); }
+  get statusBadge() { return Spectra.get("#auth-status-badge"); }
+
+  async open() {
+    await Spectra.navigate("/#auth");
+  }
+}
+
+export default new AuthPage();

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

@@ -20,6 +20,11 @@ class MatchersPage {
   get focusInput() { return Spectra.get("~focus-input"); }
   get productCards() { return Spectra.getAll("~product-item-1, ~product-item-2, ~product-item-3, ~product-item-4"); }
   get emptyList() { return Spectra.getAll("~empty-list-item"); }
+  get overviewSection() { return Spectra.get("#overview-section"); }
+  // Scoped lookups via element.get() — resolved within overview-section's own bounds (Android
+  // has no ancestor API, so this is a bounds-containment lookup), not screen-wide.
+  overviewSubtitle() { return this.overviewSection.get("#demo-page-subtitle"); }
+  overviewOutsideElement() { return this.overviewSection.get("~submit-button"); }
 
   // API Demo elements
   get fetchApiButton() { return Spectra.get("~fetch-api-btn"); }
@@ -46,6 +51,14 @@ class MatchersPage {
       const isDrawerOpen = await Spectra.get("~close-sidebar-btn").isDisplayed().catch(() => false);
       if (!isDrawerOpen) {
         await Spectra.get("~toggle-sidebar-btn").click();
+        // The mobile drawer is a React Native `<Modal>` — a separate OS-level window with its own
+        // slide-in animation, not a plain re-rendered View — so its content (including every
+        // nav-item below) isn't in the accessibility tree at all until Android actually finishes
+        // creating that window, which is async and occasionally slow under load. Without this
+        // wait, clicking a nav item right after the toggle relies entirely on click()'s own
+        // poll-retry to bridge that gap, which can eat most of the ~10s implicit-wait budget when
+        // the Modal is slow to materialize.
+        await Spectra.get("~close-sidebar-btn").waitForElement(10000);
       }
       if (section) {
         await Spectra.get(`~nav-item-${section}`).click();

package/templates/default/page-objects/MatchersPage/web.ts

@@ -16,6 +16,11 @@ class MatchersPage {
   get focusInput() { return Spectra.get("#demo-focus-input"); }
   get productCards() { return Spectra.getAll(".demo-product-card"); }
   get emptyList() { return Spectra.getAll("#demo-empty-list > *"); }
+  get overviewSection() { return Spectra.get("#overview"); }
+  // Scoped lookups via element.get() — resolved within overview-section's own subtree, not
+  // document-wide.
+  overviewSubtitle() { return this.overviewSection.get("#demo-page-subtitle"); }
+  overviewOutsideElement() { return this.overviewSection.get("#demo-submit-btn"); }
 
   // API Interception & Mocking elements
   get fetchApiButton() { return Spectra.get("#fetch-api-btn"); }

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

@@ -20,9 +20,15 @@ class PlaygroundPage {
 
   async open() {
     try {
+      // See MatchersPage.open()'s equivalent comment: waits for the cold-start home screen, then
+      // for the drawer Modal to actually finish materializing before clicking a nav item inside
+      // it — both races that otherwise surface as an occasional ~10s stall on the next click.
+      await Spectra.get("~toggle-sidebar-btn").waitForElement(30000);
+
       const isDrawerOpen = await Spectra.get("~close-sidebar-btn").isDisplayed().catch(() => false);
       if (!isDrawerOpen) {
         await Spectra.get("~toggle-sidebar-btn").click();
+        await Spectra.get("~close-sidebar-btn").waitForElement(10000);
       }
       await Spectra.get("~nav-item-playground").click();
     } catch {}

package/templates/default/specs/ApiInterception/TC-0012-direct-and-late-response/common.test.ts

@@ -19,15 +19,12 @@ it("Intercept a direct (immediate) response and a late (delayed) response using
   // Late (delayed) response — same mock rule, switched to hold the response back via `delayMs`.
   // The loading indicator must still be visible right after the click, proving this is real
   // network-level latency (the request genuinely stays pending) rather than a client-side-only
-  // spinner timer. The indicator is a non-accessible transient whose a11y entry lags the render,
-  // so a short hold raced the (now much faster) action poll; a full second makes it reliably
-  // observable while the delayed response still renders within the hard-capped 2s assertion budget
-  // the next assertions run under. The eventual correct status/content proves the delayed response
-  // arrived and rendered — this doesn't also assert the indicator later disappears via
-  // `shouldNotExist`, for the same 2s-cap margin reason.
-  await mock.respondWith(Fixture.apiData.mockPosts, { delayMs: 1000 });
+  // spinner timer. The delay is set past the default assertion timeout on purpose, to demonstrate
+  // the per-assertion `{ timeoutMs }` override below — without it, these assertions would fail-fast
+  // before the delayed response ever arrives.
+  await mock.respondWith(Fixture.apiData.mockPosts, { delayMs: 2500 });
   await MatchersPage.fetchApiButton.click();
   await MatchersPage.fetchLoadingIndicator.shouldBeVisible();
-  await MatchersPage.fetchStatusBadge.shouldHaveText("200 OK");
-  await MatchersPage.fetchedItems.shouldHaveLength(Fixture.apiData.mockPosts.length);
+  await MatchersPage.fetchStatusBadge.shouldHaveText("200 OK", { timeoutMs: 3500 });
+  await MatchersPage.fetchedItems.shouldHaveLength(Fixture.apiData.mockPosts.length, { timeoutMs: 3500 });
 });

package/templates/default/specs/Authentication/TC-0021-seed-authenticated-session/mobile.test.ts

@@ -0,0 +1,7 @@
+it("Seed an authenticated session via Spectra.seedSession() instead of the real login UI", async () => {
+  // The deep link asks the app to log itself in against a known test account and persist the
+  // result itself — no login form was ever touched.
+  await Spectra.seedSession();
+
+  await AuthPage.statusBadge.shouldHaveText("Authenticated as demo@testspectra.dev");
+});

package/templates/default/specs/Authentication/TC-0021-seed-authenticated-session/spec.md

@@ -0,0 +1,19 @@
+---
+id: TC-0021-seed-authenticated-session
+title: Seed an authenticated session via Spectra.seedSession() instead of the real login UI
+priority: High
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+  mobile: automated
+---
+
+# Seed an authenticated session via Spectra.seedSession() instead of the real login UI
+
+## Test Steps
+1. Call the `seedSession` support action — logs in via a direct API call instead of walking
+   through a login form (web: host-side `fetch()` + `Spectra.browser.setCookies()` applies the
+   resulting `HttpOnly` cookie to the browser; mobile: a deep link asks the app to log itself in
+   against a known test account and persist the result itself)
+2. Assert the app reflects an authenticated state

package/templates/default/specs/Authentication/TC-0021-seed-authenticated-session/web.test.ts

@@ -0,0 +1,9 @@
+it("Seed an authenticated session via Spectra.seedSession() instead of the real login UI", async () => {
+  // Logs in via a direct host-side API call and applies the resulting HttpOnly cookie straight
+  // to the browser — no login form was ever touched.
+  await Spectra.seedSession();
+
+  await AuthPage.open();
+  await AuthPage.checkStatusButton.click();
+  await AuthPage.statusBadge.shouldHaveText("Authenticated as demo@testspectra.dev");
+});

package/templates/default/specs/Authentication/suite.md

@@ -0,0 +1,9 @@
+---
+id: suite-authentication
+name: Authentication
+description: Skipping the real login UI by seeding an authenticated session via a direct API call
+executionOrder: 2.6
+parallel: true
+---
+
+# Suite: Authentication

package/templates/default/specs/BrowserContext/TC-0022-history-navigation/mobile.test.ts

@@ -0,0 +1,17 @@
+it("Navigate browser history with Spectra.back(), forward(), and refresh()", async () => {
+  // Same cold-start race as DeepLink/TC-0018 — wait for the home screen before firing the deep
+  // link so it isn't racing the app's own still-in-progress initial boot.
+  await Spectra.get("~toggle-sidebar-btn").waitForElement(30000);
+
+  await Spectra.navigate("testspectra-demo://deeplink-target");
+  await Spectra.get("~deeplink-target-marker").waitForElement(10000);
+
+  // Spectra.back() on Android presses the hardware back key — distinct from tapping the screen's
+  // own "‹ Back" button (already covered by DeepLink/TC-0018) — and should pop the nav stack back
+  // to Home exactly the same way.
+  await Spectra.back();
+  await Spectra.get("~toggle-sidebar-btn").waitForElement(10000);
+
+  // Spectra.forward()/Spectra.refresh() have no native-app equivalent (no browser history, no
+  // page reload) — they're intentional no-ops on Android, so there's nothing to assert here.
+});

package/templates/default/specs/BrowserContext/TC-0022-history-navigation/spec.md

@@ -0,0 +1,28 @@
+---
+id: TC-0022-history-navigation
+title: Navigate browser/app history with Spectra.back(), forward(), and refresh()
+priority: Medium
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+  mobile: automated
+---
+
+# Navigate browser/app history with Spectra.back(), forward(), and refresh()
+
+## Test Steps
+
+### Web
+1. Navigate to two distinct real URLs in sequence, each pushing its own genuine browser history
+   entry (this demo app's in-app hash navigation does not — see the test's own comment)
+2. Verify `Spectra.back()` returns to the previously visited URL
+3. Verify `Spectra.forward()` replays the entry just undone
+4. Verify `Spectra.refresh()` reloads the document while the current URL survives
+
+### Mobile
+1. Navigate to a native route via deep link
+2. Verify `Spectra.back()` (Android hardware back key) pops back to the Home screen
+
+`Spectra.forward()`/`Spectra.refresh()` have no native-app equivalent (no browser history, no page
+reload) and are intentional no-ops on Android — only `Spectra.back()` is exercised on mobile.

package/templates/default/specs/BrowserContext/TC-0022-history-navigation/web.test.ts

@@ -0,0 +1,26 @@
+it("Navigate browser history with Spectra.back(), forward(), and refresh()", async () => {
+  await MatchersPage.open();
+
+  // This demo app is single-page — its in-app "navigation" (Spectra.navigate("/#section")) only
+  // ever sets window.location.hash, which this browser does not push as a traversable history
+  // entry (history.length never grows), so there is nothing for back()/forward() to jump between.
+  // Two distinct real paths give them something real: Vite's dev server serves the same SPA shell
+  // for any path, but the browser still treats each as its own document and pushes a genuine
+  // history entry — exactly like a real multi-page site would.
+  await Spectra.navigate("/history-nav-a");
+  await Spectra.browser.shouldContainUrl("/history-nav-a");
+
+  await Spectra.navigate("/history-nav-b");
+  await Spectra.browser.shouldContainUrl("/history-nav-b");
+
+  await Spectra.back();
+  await Spectra.browser.shouldContainUrl("/history-nav-a");
+
+  await Spectra.forward();
+  await Spectra.browser.shouldContainUrl("/history-nav-b");
+
+  // The document reloads, but the current URL survives it.
+  await Spectra.refresh();
+  await Spectra.browser.shouldBeLoaded();
+  await Spectra.browser.shouldContainUrl("/history-nav-b");
+});

package/templates/default/specs/ContentMatchers/TC-0020-scoped-element-access/common.test.ts

@@ -0,0 +1,14 @@
+it("element.get()/getAll() resolves a child scoped to its parent's own subtree", async () => {
+  await MatchersPage.open();
+  await MatchersPage.overviewSection.shouldBeVisible();
+
+  // Positive: the subtitle is a real descendant of the overview section, so the scoped lookup
+  // resolves it.
+  await MatchersPage.overviewSubtitle().shouldExist();
+
+  // Negative (the actual scoping proof): the submit button lives in a different section
+  // entirely. If .get() weren't genuinely scoped (e.g. silently fell back to a page-wide
+  // lookup), this would incorrectly resolve to the globally-existing element instead of
+  // correctly not finding it.
+  await MatchersPage.overviewOutsideElement().shouldNotExist();
+});

package/templates/default/specs/ContentMatchers/TC-0020-scoped-element-access/spec.md

@@ -0,0 +1,21 @@
+---
+id: TC-0020-scoped-element-access
+title: element.get()/getAll() resolves a child scoped to its parent's own subtree
+priority: High
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+  mobile: automated
+---
+
+# element.get()/getAll() resolves a child scoped to its parent's own subtree
+
+## Test Steps
+1. Open the matchers page and assert the overview section is visible
+2. From the overview section, resolve the page subtitle via `.get()` and assert it exists — the
+   subtitle is a real descendant, so the scoped lookup finds it
+3. From the same overview section, resolve the submit button via `.get()` and assert it does NOT
+   exist — the submit button lives in a different section entirely, so this only passes if the
+   lookup is genuinely scoped to overview's own subtree rather than silently falling back to a
+   page-wide match

package/templates/default/specs/EnvironmentConfig/TC-0019-read-custom-environment-variable/common.test.ts

@@ -0,0 +1,5 @@
+it("Verify a custom environmentVariables entry is readable via Spectra.env", async () => {
+  if (Spectra.env.DEMO_API_MODE !== "sandbox") {
+    throw new Error(`Expected Spectra.env.DEMO_API_MODE to be "sandbox", got "${Spectra.env.DEMO_API_MODE}"`);
+  }
+});

package/templates/default/specs/EnvironmentConfig/TC-0019-read-custom-environment-variable/spec.md

@@ -0,0 +1,16 @@
+---
+id: TC-0019-read-custom-environment-variable
+title: Verify a custom environmentVariables entry is readable via Spectra.env
+priority: Medium
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+  mobile: automated
+---
+
+# Verify a custom environmentVariables entry is readable via Spectra.env
+
+## Test Steps
+1. Read the DEMO_API_MODE variable via the typed Spectra.env
+2. Assert it matches the value configured in spectra.config.ts's executionConfig.environmentVariables

package/templates/default/specs/EnvironmentConfig/suite.md

@@ -0,0 +1,9 @@
+---
+id: suite-environment-config
+name: EnvironmentConfig
+description: Reading custom executionConfig.environmentVariables values via Spectra.env
+executionOrder: 2.3
+parallel: true
+---
+
+# Suite: EnvironmentConfig

package/templates/default/spectra.config.ts

@@ -6,17 +6,8 @@ export default defineConfig({
     maxConcurrentSessions: "1",
     headless: true,
     implicitWait: "5000",
-    pageLoadTimeout: "30000",
-    scriptTimeout: "30000",
     parallelizationMode: "testcase",
   },
-  browsers: [
-    {
-      id: "chrome-desktop",
-      type: "chrome",
-      mobileEmulation: false,
-    },
-  ],
   androidConfig: {
     driverServer: "tcp://127.0.0.1:8200",
     appPackage: "dev.testspectra.demoapp",
@@ -51,17 +42,11 @@ export default defineConfig({
       },
     ],
   },
-  loadConfig: {
-    virtualUsers: "10",
-    duration: "1m",
-  },
-  loadStages: [],
-  thresholds: [],
   executionConfig: {
     networkMonitoringEnabled: true,
     fastResponseTime: "200",
     normalResponseTime: "1000",
     monitoredDomains: [],
-    environmentVariables: [],
+    environmentVariables: { DEMO_API_MODE: "sandbox" },
   },
 });