@testspectra/cli 1.0.70 → 1.1.0-rc.1

package/templates/default/specs/ApiSeeding/hooks/before/common.hook.ts

@@ -0,0 +1,28 @@
+// Suite-level `before` hook — runs once before this suite's tests. Hooks run in the same worker
+// process/global scope as the test files, so data seeded here is handed to tests via a plain
+// `globalThis` namespace rather than a return value (hooks don't have a return channel).
+//
+// Seeds against the demo server's own self-hosted API (started with `--demo`) instead of an
+// external public API, so the round trip is deterministic and offline-safe — same seed-in-
+// `before`, clean-up-in-`after` hook mechanics, with a REAL network round trip, just against a
+// server we control. Because the hook runs on the HOST (not the device), this suite needs the
+// demo server up on the host: run it with `--demo` (e.g. `spectra run ... -t android --demo`).
+// Swap the base URL for a real backend's seeding endpoint in an actual project.
+export default async function () {
+  const res = await fetch("http://localhost:5200/api/posts", {
+    method: "POST",
+    headers: { "Content-Type": "application/json; charset=UTF-8" },
+    body: JSON.stringify({
+      title: "TestSpectra seeded post",
+      body: "Created by ApiSeeding's before hook for TC-0014.",
+      userId: 1,
+    }),
+  });
+
+  if (!res.ok) {
+    throw new Error(`ApiSeeding before hook: failed to seed post (${res.status} ${res.statusText})`);
+  }
+
+  const seeded = await res.json();
+  (globalThis as any).__apiSeeding = { seededPost: seeded, cleanedUp: false };
+}

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

@@ -0,0 +1,9 @@
+---
+id: suite-api-seeding
+name: ApiSeeding
+description: Seeding and cleaning up test data via a real free public API in before/after hooks
+executionOrder: 2.5
+parallel: true
+---
+
+# Suite: ApiSeeding

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-0007-title-and-navigation/mobile.test.ts

@@ -1,3 +1,9 @@
-it("should verify title on Mobile", async () => {
+it("Verify page title and sidebar navigation links", async () => {
   await MatchersPage.open();
+
+  // Navigation sidebar collection verification
+  await NavigationPage.sidebarLinks.shouldHaveLengthGreaterThan(0);
+
+  // Close sidebar drawer
+  await NavigationPage.closeSidebarButton.click();
 });

package/templates/default/specs/BrowserContext/TC-0007-title-and-navigation/spec.md

@@ -10,3 +10,8 @@ coverage:
 ---
 
 # Verify page title and sidebar navigation links
+
+## Test Steps
+1. Open matchers page
+2. Verify browser page title contains TestSpectra
+3. Verify sidebar navigation links length is greater than 0

package/templates/default/specs/BrowserContext/TC-0007-title-and-navigation/web.test.ts

@@ -1,5 +1,19 @@
-it("should verify browser page title and navigation links on Web", async () => {
+it("Verify page title and sidebar navigation links", async () => {
   await MatchersPage.open();
-  await browser.shouldContainTitle("TestSpectra");
-  await NavigationPage.sidebarLinks.should("have.length.greaterThan", 0);
+
+  // Browser title assertions
+  await Spectra.browser.shouldHaveTitle("TestSpectra — Matchers API Reference");
+  await Spectra.browser.shouldContainTitle("TestSpectra");
+
+  // Browser URL assertions
+  const currentUrl = await browser.getUrl();
+  await Spectra.browser.shouldHaveUrl(currentUrl);
+  await Spectra.browser.shouldContainUrl("localhost:5173");
+
+  // Page lifecycle and console error diagnostics
+  await Spectra.browser.shouldBeLoaded();
+  await Spectra.browser.shouldHaveNoConsoleErrors();
+
+  // Navigation sidebar collection verification
+  await NavigationPage.sidebarLinks.shouldHaveLengthGreaterThan(0);
 });

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-0005-text-and-values/common.test.ts

@@ -0,0 +1,26 @@
+// A single common.test.ts, not a web.test.ts/mobile.test.ts pair — the orchestrator's test-case
+// discovery recognizes "common" as a platform stem for every target (web, android, ios, mobile),
+// so this one file runs unmodified on all of them. This works here because every Spectra.*
+// command below is genuinely platform-agnostic (the DSL layer has zero platform branching by
+// design) and MatchersPage's selectors are already abstracted per-platform behind identically-
+// named getters — nothing in this specific test depends on a page origin, a native-only gesture,
+// or a browser-chrome-only assertion (see TC-0013's real-network test for a case that CAN'T be
+// shared this way: Android has no implicit page origin to resolve a relative fetch URL against,
+// so the URL itself has to differ per platform even though the commands stay identical).
+it("Verify exact text, substring text, and input values", async () => {
+  await MatchersPage.open("text");
+
+  // Text assertions (positive and negative)
+  await MatchersPage.exactText.shouldHaveText(Fixture.playgroundData.welcomeText);
+  await MatchersPage.exactText.shouldNotHaveText("Unexpected Text");
+
+  await MatchersPage.partialText.shouldContainText("Welcome");
+  await MatchersPage.partialText.shouldNotContainText("Goodbye");
+
+  // Value assertions (positive and negative)
+  await MatchersPage.emailInput.shouldHaveValue(Fixture.playgroundData.defaultEmail);
+  await MatchersPage.emailInput.shouldNotHaveValue("wrong.user@testspectra.dev");
+
+  await MatchersPage.tokenInput.shouldContainValue("JWT_");
+  await MatchersPage.tokenInput.shouldNotContainValue("EXPIRED_SESSION");
+});

package/templates/default/specs/ContentMatchers/TC-0005-text-and-values/spec.md

@@ -10,3 +10,10 @@ coverage:
 ---
 
 # Verify exact text, substring text, and input values
+
+## Test Steps
+1. Open text matchers section in matchers page
+2. Verify exact text matches playground welcome text
+3. Verify partial text contains welcome keyword
+4. Verify email input value matches default email
+5. Verify token input value contains JWT prefix

package/templates/default/specs/ContentMatchers/TC-0006-collections-and-empty/mobile.test.ts

@@ -1,3 +1,11 @@
-it("should verify collection length on Mobile", async () => {
+it("Verify collection lengths, counts, and empty lists", async () => {
   await MatchersPage.open("length");
+
+  // Receiver assertion methods
+  await MatchersPage.productCards.shouldHaveLength(4);
+  await MatchersPage.productCards.shouldNotHaveLength(0);
+  await MatchersPage.productCards.shouldHaveLengthGreaterThan(0);
+  await MatchersPage.productCards.shouldHaveLengthLessThan(10);
+  await MatchersPage.emptyList.shouldBeEmpty();
+  await MatchersPage.productCards.shouldNotBeEmpty();
 });

package/templates/default/specs/ContentMatchers/TC-0006-collections-and-empty/spec.md

@@ -10,3 +10,8 @@ coverage:
 ---
 
 # Verify collection lengths, counts, and empty lists
+
+## Test Steps
+1. Open collection length section in matchers page
+2. Assert product cards count equals 4 and is greater than 0
+3. Assert empty list container is empty

package/templates/default/specs/ContentMatchers/TC-0006-collections-and-empty/web.test.ts

@@ -1,6 +1,11 @@
-it("should verify collection lengths and empty lists on Web", async () => {
+it("Verify collection lengths, counts, and empty lists", async () => {
   await MatchersPage.open("length");
-  await MatchersPage.productCards.should("have.length", 4);
-  await MatchersPage.productCards.should("have.length.greaterThan", 0);
-  await MatchersPage.emptyList.should("be.empty");
+
+  // Receiver assertion methods
+  await MatchersPage.productCards.shouldHaveLength(4);
+  await MatchersPage.productCards.shouldNotHaveLength(0);
+  await MatchersPage.productCards.shouldHaveLengthGreaterThan(0);
+  await MatchersPage.productCards.shouldHaveLengthLessThan(10);
+  await MatchersPage.emptyList.shouldBeEmpty();
+  await MatchersPage.productCards.shouldNotBeEmpty();
 });

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/DeepLink/TC-0018-navigate-via-deep-link/mobile.test.ts

@@ -0,0 +1,28 @@
+it("Navigate directly to a native route via Spectra.navigate() and an Android deep link", async () => {
+  // The orchestrator's own bootstrap launches the app (fire-and-forget, ~1.5s wait) before any
+  // test code runs at all — other tests never notice because their first action is a click()
+  // with its own generous poll budget, which absorbs whatever's left of the cold start. This
+  // test's first action is Spectra.navigate() itself, which is also fire-and-forget and has no
+  // such budget, so without this it races the deep-link intent against the app's own still-in-
+  // progress initial boot. Waiting for the home screen to actually be up first avoids that race.
+  await Spectra.get("~toggle-sidebar-btn").waitForElement(30000);
+
+  // No prior navigation, no button clicks — this jumps straight to the route via
+  // `adb shell am start`, exactly like opening the app from a push notification or an
+  // external link would.
+  await Spectra.navigate("testspectra-demo://deeplink-target");
+  await Spectra.get("~deeplink-target-marker").waitForElement(10000);
+
+  await Spectra.get("~deeplink-target-marker").shouldHaveText("deeplink-target");
+  await Spectra.get("~deeplink-received-message").shouldHaveText("(none)");
+
+  await Spectra.get("~back-to-home-btn").click();
+
+  // Deep links can carry query params — assert they survive the intent all the way to the screen.
+  await Spectra.navigate("testspectra-demo://deeplink-target?message=hello-from-deep-link");
+
+  await Spectra.get("~deeplink-received-message").waitForElement(10000);
+  await Spectra.get("~deeplink-received-message").shouldHaveText("hello-from-deep-link");
+
+  await Spectra.get("~back-to-home-btn").click();
+});

package/templates/default/specs/DeepLink/TC-0018-navigate-via-deep-link/spec.md

@@ -0,0 +1,29 @@
+---
+id: TC-0018-navigate-via-deep-link
+title: Navigate directly to a native route via Spectra.navigate() and an Android deep link
+priority: High
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: unsupported
+  mobile: automated
+---
+
+# Navigate directly to a native route via Spectra.navigate() and an Android deep link
+
+On Android, `Spectra.navigate(uri)` runs `adb shell am start -a android.intent.action.VIEW -d
+<uri>` against the app's own registered scheme (`testspectra-demo://`, declared in
+`app.json`/`AndroidManifest.xml`) — jumping straight to a route without walking through the UI
+first, the same way a push notification or an external link would open the app in production.
+
+Web coverage is `unsupported`: on web, `Spectra.navigate()` already does the equivalent thing
+via a normal URL (see any other TC's `browser.url(...)`/`Spectra.navigate(...)` call) — there's no
+separate "deep link" concept to demonstrate there.
+
+## Test Steps
+1. Wait for the app home screen to finish booting
+2. Navigate via a deep link to the target route without query params
+3. Assert the target marker is shown and the received message is "(none)"
+4. Navigate via a deep link carrying a query-param message
+5. Assert the received message matches the deep-link param
+6. Return to the home screen

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

@@ -0,0 +1,9 @@
+---
+id: suite-deep-link
+name: DeepLink
+description: Navigating directly to a native route via Spectra.navigate() and an adb deep link
+executionOrder: 2.2
+parallel: true
+---
+
+# Suite: DeepLink

package/templates/default/specs/ElementMatchers/TC-0003-visibility-and-dom/mobile.test.ts

@@ -1,3 +1,11 @@
-it("should verify visibility on Mobile", async () => {
+it("Verify element visibility and existence matchers", async () => {
   await MatchersPage.open("visibility");
+
+  // Element visibility (positive and negative)
+  await MatchersPage.visibleElement.shouldBeVisible();
+  await MatchersPage.hiddenElement.shouldNotBeVisible();
+
+  // DOM existence (positive and negative)
+  await MatchersPage.existingElement.shouldExist();
+  await Spectra.get("~non-existent-element").shouldNotExist();
 });

package/templates/default/specs/ElementMatchers/TC-0003-visibility-and-dom/spec.md

@@ -10,3 +10,8 @@ coverage:
 ---
 
 # Verify element visibility and existence matchers
+
+## Test Steps
+1. Open visibility section in matchers page
+2. Assert visible element has be.visible state
+3. Assert existing element exists in DOM

package/templates/default/specs/ElementMatchers/TC-0003-visibility-and-dom/web.test.ts

@@ -1,5 +1,11 @@
-it("should verify be.visible and exist matchers on Web", async () => {
+it("Verify element visibility and existence matchers", async () => {
   await MatchersPage.open("visibility");
-  await MatchersPage.visibleElement.should("be.visible");
-  await MatchersPage.existingElement.should("exist");
+
+  // Element visibility (positive and negative)
+  await MatchersPage.visibleElement.shouldBeVisible();
+  await MatchersPage.hiddenElement.shouldNotBeVisible();
+
+  // DOM existence (positive and negative)
+  await MatchersPage.existingElement.shouldExist();
+  await Spectra.get("#demo-non-existent-el").shouldNotExist();
 });

package/templates/default/specs/ElementMatchers/TC-0004-states-and-attributes/mobile.test.ts

@@ -1,3 +1,29 @@
-it("should verify button state on Mobile", async () => {
+it("Verify button state, checkbox, radio and attributes", async () => {
   await MatchersPage.open("state");
+
+  // Interactivity & state assertions
+  await MatchersPage.submitButton.shouldBeEnabled();
+  await MatchersPage.submitButton.shouldBeClickable();
+
+  await MatchersPage.disabledButton.shouldBeDisabled();
+  await MatchersPage.disabledButton.shouldNotBeClickable();
+
+  // Checked states
+  await MatchersPage.checkbox.shouldNotBeChecked();
+  await MatchersPage.radio.shouldBeChecked();
+
+  // Focus states
+  await MatchersPage.focusInput.shouldNotBeFocused();
+  await MatchersPage.focusInput.click();
+  await MatchersPage.focusInput.shouldBeFocused();
+
+  // Class, Attribute, and CSS assertions
+  await MatchersPage.activeTab.shouldHaveClass("is-active");
+  await MatchersPage.activeTab.shouldNotHaveClass("is-hidden");
+
+  await MatchersPage.navLink.shouldHaveAttribute("accessibilityLabel", "nav-link");
+  await MatchersPage.navLink.shouldNotHaveAttribute("disabled");
+
+  await MatchersPage.styledElement.shouldHaveCss("color", "rgba(239,68,68,1)");
+  await MatchersPage.styledElement.shouldNotHaveCss("color", "rgba(0,0,255,1)");
 });

package/templates/default/specs/ElementMatchers/TC-0004-states-and-attributes/spec.md

@@ -10,3 +10,10 @@ coverage:
 ---
 
 # Verify button state, checkbox, radio and attributes
+
+## Test Steps
+1. Open element state section in matchers page
+2. Assert submit button is enabled and disabled button is disabled
+3. Assert terms checkbox is not checked
+4. Assert active tab has is-active class
+5. Assert navigation link has correct href attribute

package/templates/default/specs/ElementMatchers/TC-0004-states-and-attributes/web.test.ts

@@ -1,8 +1,29 @@
-it("should verify enabled/disabled states and HTML attributes on Web", async () => {
+it("Verify button state, checkbox, radio and attributes", async () => {
   await MatchersPage.open("state");
-  await MatchersPage.submitButton.should("be.enabled");
-  await MatchersPage.disabledButton.should("be.disabled");
-  await MatchersPage.checkbox.should("not.be.checked");
-  await MatchersPage.activeTab.should("have.class", "is-active");
-  await MatchersPage.navLink.should("have.attr", "href", Fixture.playgroundData.dashboardHref);
+
+  // Interactivity & state assertions
+  await MatchersPage.submitButton.shouldBeEnabled();
+  await MatchersPage.submitButton.shouldBeClickable();
+
+  await MatchersPage.disabledButton.shouldBeDisabled();
+  await MatchersPage.disabledButton.shouldNotBeClickable();
+
+  // Checked states
+  await MatchersPage.checkbox.shouldNotBeChecked();
+  await MatchersPage.radio.shouldBeChecked();
+
+  // Focus states
+  await MatchersPage.focusInput.shouldNotBeFocused();
+  await MatchersPage.focusInput.click();
+  await MatchersPage.focusInput.shouldBeFocused();
+
+  // Class, Attribute, and CSS assertions
+  await MatchersPage.activeTab.shouldHaveClass("is-active");
+  await MatchersPage.activeTab.shouldNotHaveClass("is-hidden");
+
+  await MatchersPage.navLink.shouldHaveAttribute("href", Fixture.playgroundData.dashboardHref);
+  await MatchersPage.navLink.shouldNotHaveAttribute("disabled");
+
+  await MatchersPage.styledElement.shouldHaveCss("color", "rgba(239,68,68,1)");
+  await MatchersPage.styledElement.shouldNotHaveCss("color", "rgba(0,0,255,1)");
 });

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

@@ -1,6 +1,7 @@
 ---
+name: Untitled Suite
 id: suite-element-matchers
-name: ElementMatchers
+
 description: Element visibility, existence, form states and attributes
 executionOrder: 1.0
 parallel: true

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/specs/PermissionRationale/TC-0010-camera-permission-allow/mobile.test.ts

@@ -0,0 +1,26 @@
+it("Confirm custom rationale dialog Allow triggers real permission request and grants camera access", async () => {
+  // Navigate to the dedicated permission-rationale route (real router path, not a hash/scroll
+  // section) via the header link.
+  await Spectra.get("~nav-to-permission-demo").click();
+
+  await Spectra.get("~permission-status-text").shouldHaveText("Not requested");
+
+  await Spectra.get("~request-camera-permission-btn").click();
+
+  // The custom rationale dialog appears first — no real permission dialog yet.
+  await Spectra.get("~rationale-allow-btn").shouldBeVisible();
+
+  await Spectra.get("~rationale-allow-btn").click();
+
+  // Confirming the custom dialog triggers the real Android permission request. Grant it
+  // on-demand right now, exactly like a real device automation flow would — the app itself
+  // is resilient to the resulting race (see permission-rationale.tsx's recheck loop), so the
+  // status still lands on "Granted" below regardless of exactly when this call resolves
+  // relative to the OS dialog.
+  await Spectra.grantPermission("android.permission.CAMERA");
+
+  await Spectra.get("~permission-status-text").shouldHaveText("Granted");
+
+  // Return to the home screen so later suites in the same batch don't inherit this route.
+  await Spectra.get("~back-to-home-btn").click();
+});

package/templates/default/specs/PermissionRationale/TC-0010-camera-permission-allow/spec.md

@@ -0,0 +1,22 @@
+---
+id: TC-0010-camera-permission-allow
+title: Confirm custom rationale dialog Allow triggers real permission request and grants camera access
+priority: High
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: unsupported
+  mobile: automated
+---
+
+# Confirm custom rationale dialog Allow triggers real permission request and grants camera access
+
+## Test Steps
+1. Navigate to the permission rationale demo route
+2. Assert the initial status is "Not requested"
+3. Click the request camera permission button
+4. Assert the custom rationale dialog appears
+5. Click Allow
+6. Grant the real camera permission on demand
+7. Assert the status becomes "Granted"
+8. Return to the home screen

package/templates/default/specs/PermissionRationale/TC-0011-camera-permission-deny/mobile.test.ts

@@ -0,0 +1,13 @@
+it("Confirm custom rationale dialog Deny never triggers the real permission request", async () => {
+  await Spectra.get("~nav-to-permission-demo").click();
+
+  await Spectra.get("~request-camera-permission-btn").click();
+  await Spectra.get("~rationale-deny-btn").shouldBeVisible();
+  await Spectra.get("~rationale-deny-btn").click();
+
+  // Deliberately never calls the real permission API — the status must reflect the custom
+  // dialog's own decision, not any OS-level request.
+  await Spectra.get("~permission-status-text").shouldHaveText("Declined in rationale dialog");
+
+  await Spectra.get("~back-to-home-btn").click();
+});