@testspectra/cli 1.1.6 → 1.1.8-rc.1

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

@@ -1,4 +1,4 @@
-export class MatchersPage {
+class MatchersPage {
   get visibleElement() { return Spectra.get("~visible-element"); }
   get hiddenElement() { return Spectra.get("~hidden-element"); }
   get existingElement() { return Spectra.get("~existing-element"); }
@@ -11,18 +11,27 @@ export class MatchersPage {
   get tokenInput() { return Spectra.get("~token-input"); }
   get exactText() { return Spectra.get("~exact-text"); }
   get partialText() { return Spectra.get("~partial-text"); }
-  get activeTab() { return Spectra.get("~active-tab"); }
+  // `#` = native id (RN testID → resource-id). Its accessibility label deliberately reads
+  // "active-tab is-active" (RN exposes no CSS classes, so the class is carried in the a11y label
+  // for `shouldHaveClass`), so it isn't addressable by the a11y-id form `~active-tab`.
+  get activeTab() { return Spectra.get("#active-tab"); }
   get navLink() { return Spectra.get("~nav-link"); }
   get styledElement() { return Spectra.get("~styled-element"); }
   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"); }
   get fetchStatusBadge() { return Spectra.get("~fetch-status-badge"); }
   get fetchedItems() { return Spectra.getAll("~api-post-item"); }
   get fetchLoadingIndicator() { return Spectra.get("~fetch-loading-indicator"); }
+  get fetchCustomUrlInput() { return Spectra.get("~fetch-custom-url"); }
   get postTitleInput() { return Spectra.get("~post-title-input"); }
   get postBodyInput() { return Spectra.get("~post-body-input"); }
   get submitPostButton() { return Spectra.get("~submit-post-btn"); }
@@ -32,9 +41,24 @@ export class MatchersPage {
 
   async open(section = "") {
     try {
+      // A fresh app process (relaunched by the orchestrator's bootstrap before every suite) has to
+      // fetch, parse, and execute the RN JS bundle from Metro before anything is on screen — on a
+      // cold start this can take well past a normal action's poll budget. Wait for the home screen
+      // itself first so that timing doesn't silently swallow the sidebar click below and leave the
+      // real failure to surface confusingly on whatever element the test touches next.
+      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();
+        // 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

@@ -1,4 +1,4 @@
-export class MatchersPage {
+class MatchersPage {
   get visibleElement() { return Spectra.get("#demo-visible-el"); }
   get hiddenElement() { return Spectra.get("#demo-hidden-el"); }
   get existingElement() { return Spectra.get("#demo-existing-el"); }
@@ -16,12 +16,18 @@ export 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"); }
   get fetchStatusBadge() { return Spectra.get("#fetch-status-badge"); }
   get fetchedItems() { return Spectra.getAll(".api-fetched-item"); }
   get fetchLoadingIndicator() { return Spectra.get("#fetch-loading-indicator"); }
+  get fetchCustomUrlInput() { return Spectra.get("#fetch-custom-url-input"); }
   get postTitleInput() { return Spectra.get("#post-input-title"); }
   get postBodyInput() { return Spectra.get("#post-input-body"); }
   get submitPostButton() { return Spectra.get("#submit-post-btn"); }
@@ -30,7 +36,7 @@ export class MatchersPage {
   get postResponseJson() { return Spectra.get("#post-response-json"); }
 
   async open(section = "") {
-    await browser.url("/" + (section ? "#" + section : ""));
+    await Spectra.navigate("/" + (section ? "#" + section : ""));
   }
 }
 

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

@@ -1,4 +1,4 @@
-export class NavigationPage {
+class NavigationPage {
   get sidebarLinks() {
     return Spectra.getAll(
       "~nav-item-overview, ~nav-item-element-matchers, ~nav-item-visibility, ~nav-item-existence, ~nav-item-state, ~nav-item-value, ~nav-item-text, ~nav-item-class-attr, ~nav-item-browser-matchers, ~nav-item-url, ~nav-item-title, ~nav-item-collection-matchers, ~nav-item-length, ~nav-item-api-matchers, ~nav-item-api-fetch, ~nav-item-api-post, ~nav-item-playground"

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

@@ -1,4 +1,4 @@
-export class NavigationPage {
+class NavigationPage {
   get sidebarLinks() { return Spectra.getAll("aside a"); }
   get overviewLink() { return Spectra.get("aside a[href='#overview']"); }
   get visibilityLink() { return Spectra.get("aside a[href='#visibility']"); }

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

@@ -1,14 +1,14 @@
-export class PlaygroundPage {
+class PlaygroundPage {
   get visibleElement() { return Spectra.get("~playground-visible"); }
   get hiddenElement() { return Spectra.get("~playground-hidden"); }
   get existingElement() { return Spectra.get("~playground-existing"); }
   get removedElement() { return Spectra.get("~playground-removable"); }
   get enabledButton() { return Spectra.get("~enabled-button"); }
-  get disabledButton() { return Spectra.get("~disabled-button"); }
-  get termsCheckbox() { return Spectra.get("~terms-checkbox"); }
-  get modeRadio() { return Spectra.get("~mode-radio"); }
-  get emailInput() { return Spectra.get("~email-input"); }
-  get tokenInput() { return Spectra.get("~token-input"); }
+  get disabledButton() { return Spectra.get("~pg-disabled-button"); }
+  get termsCheckbox() { return Spectra.get("~pg-terms-checkbox"); }
+  get modeRadio() { return Spectra.get("~pg-mode-radio"); }
+  get emailInput() { return Spectra.get("~pg-email-input"); }
+  get tokenInput() { return Spectra.get("~pg-token-input"); }
   get exactText() { return Spectra.get("~exact-text-el"); }
   get partialText() { return Spectra.get("~partial-text-el"); }
   get activeTab() { return Spectra.get("~active-tab-el"); }
@@ -20,9 +20,15 @@ export 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/page-objects/PlaygroundPage/web.ts

@@ -1,4 +1,4 @@
-export class PlaygroundPage {
+class PlaygroundPage {
   get visibleElement() { return Spectra.get("#demo-visible-el-pg"); }
   get hiddenElement() { return Spectra.get("#demo-hidden-el-pg"); }
   get existingElement() { return Spectra.get("#demo-existing-el-pg"); }
@@ -19,7 +19,7 @@ export class PlaygroundPage {
   get emptyList() { return Spectra.getAll("#demo-empty-list-pg > *"); }
 
   async open() {
-    await browser.url("/#playground");
+    await Spectra.navigate("/#playground");
   }
 
   async fillCredentials(email = Fixture.playgroundData.defaultEmail, token = Fixture.playgroundData.defaultToken) {

package/templates/default/specs/ApiInterception/TC-0008-fetch-mocking/mobile.test.ts

@@ -1,11 +1,53 @@
-it("should verify GET API fetch response items and state on Mobile", async () => {
+it("Mock and assert GET API requests using browser.intercept", async () => {
   // Navigate to API Fetch section
   await MatchersPage.open("api-fetch");
 
+  // The app fetches the host demo server's self-hosted endpoint (http://localhost:5200/api/posts) —
+  // the device's global HTTP proxy (set up transparently at bootstrap) routes it through the
+  // worker's mock proxy without the app knowing or needing any special host/prefix, the same
+  // way the CDP web driver intercepts traffic for free. Clear any mock left registered by an
+  // earlier test in this same continuous session before adding this one.
+  Spectra.clearMocks();
+  const mock = await Spectra.intercept(
+    "api/posts",
+    "GET",
+    Fixture.apiData.mockPosts
+  );
+
   // Trigger fetch button in mobile demo app
   await MatchersPage.fetchApiButton.click();
 
-  // Assert status badge and response items rendered
+  // Assert status and mocked elements
   await MatchersPage.fetchStatusBadge.shouldHaveText("200 OK");
-  await MatchersPage.fetchedItems.shouldHaveLengthGreaterThan(0);
+  await MatchersPage.fetchedItems.shouldHaveLength(Fixture.apiData.mockPosts.length);
+  await MatchersPage.fetchedItems.first().shouldContainText(Fixture.apiData.mockPosts[0].title);
+
+  // Dynamically update fixture response
+  await mock.respondWith([
+    { id: 99, title: "Dynamic Updated Mock Title", body: "Updated on the fly" }
+  ]);
+  await MatchersPage.fetchApiButton.click();
+  await MatchersPage.fetchedItems.shouldHaveLength(1);
+  await MatchersPage.fetchedItems.first().shouldContainText("Dynamic Updated Mock Title");
+
+  // Reset to the base mock and queue a single one-time response — asserts a transient state
+  // (e.g. one retry attempt) without disturbing what every other call returns.
+  Spectra.clearMocks();
+  const queuedMock = await Spectra.intercept(
+    "api/posts",
+    "GET",
+    Fixture.apiData.mockPosts
+  );
+  await queuedMock.respondOnce([
+    { id: 777, title: "One-Time Queued Response", body: "Only served once" }
+  ]);
+
+  await MatchersPage.fetchApiButton.click();
+  await MatchersPage.fetchedItems.shouldHaveLength(1);
+  await MatchersPage.fetchedItems.first().shouldContainText("One-Time Queued Response");
+
+  // The queued response is consumed by the call above — this one reverts to the base rule.
+  await MatchersPage.fetchApiButton.click();
+  await MatchersPage.fetchedItems.shouldHaveLength(Fixture.apiData.mockPosts.length);
+  await MatchersPage.fetchedItems.first().shouldContainText(Fixture.apiData.mockPosts[0].title);
 });

package/templates/default/specs/ApiInterception/TC-0008-fetch-mocking/spec.md

@@ -10,3 +10,10 @@ coverage:
 ---
 
 # Mock and assert GET API requests using browser.intercept
+
+## Test Steps
+1. Open API fetch section in matchers page
+2. Intercept GET /api/posts with mock posts fixture data
+3. Click fetch API button
+4. Assert status badge displays 200 OK and rendered items match fixture
+5. Update mock response dynamically and verify updated items rendered

package/templates/default/specs/ApiInterception/TC-0008-fetch-mocking/web.test.ts

@@ -1,10 +1,14 @@
-it("should mock GET API response using browser.intercept and verify rendered items", async () => {
+it("Mock and assert GET API requests using browser.intercept", async () => {
   // Navigate to API Fetch section
   await MatchersPage.open("api-fetch");
 
-  // Setup API interception with Fixture data
-  const mock = await browser.intercept(
-    "/api/posts",
+  // The app fetches the demo server's own self-hosted endpoint (/api/posts) — served by the
+  // built-in demo app (started with `--demo`), so no external network is involved. Clear any mock
+  // left registered by an earlier test in this same continuous session before adding this one,
+  // since rules aren't scoped per-test and the first matching rule wins.
+  Spectra.clearMocks();
+  const mock = await Spectra.intercept(
+    "api/posts",
     "GET",
     Fixture.apiData.mockPosts
   );

package/templates/default/specs/ApiInterception/TC-0009-post-mocking/android.test.ts

@@ -0,0 +1,3 @@
+it('Mock and assert POST API requests using browser.intercept', async () => {
+  // TODO: Implement test steps and assertions
+});

package/templates/default/specs/ApiInterception/TC-0009-post-mocking/common.test.ts

@@ -0,0 +1,3 @@
+it('Mock and assert POST API requests using browser.intercept', async () => {
+  // TODO: Implement test steps and assertions
+});

package/templates/default/specs/ApiInterception/TC-0009-post-mocking/mobile.test.ts

@@ -1,7 +1,18 @@
-it("should verify POST API form submission and response payload on Mobile", async () => {
+it("Mock and assert POST API requests using browser.intercept", async () => {
   // Navigate to API POST section
   await MatchersPage.open("api-post");
 
+  // Setup POST API interception with status 201 — the app posts to the host demo server's
+  // self-hosted endpoint (http://localhost:5200/api/posts), transparently routed through the
+  // worker's mock proxy via the device's global HTTP proxy set up at bootstrap.
+  Spectra.clearMocks();
+  await Spectra.intercept(
+    "api/posts",
+    "POST",
+    Fixture.apiData.mockPostResponse,
+    { statusCode: 201 }
+  );
+
   // Fill in form fields from Fixture
   await MatchersPage.postTitleInput.type(Fixture.apiData.mockNewPost.title);
   await MatchersPage.postBodyInput.type(Fixture.apiData.mockNewPost.body);
@@ -9,7 +20,7 @@ it("should verify POST API form submission and response payload on Mobile", asyn
   // Submit POST form
   await MatchersPage.submitPostButton.click();
 
-  // Assert response elements and status badge
+  // Assert response elements and status
   await MatchersPage.postStatusBadge.shouldHaveText("201 Created");
   await MatchersPage.postSuccessBanner.shouldBeVisible();
   await MatchersPage.postResponseJson.shouldContainText(Fixture.apiData.mockNewPost.title);

package/templates/default/specs/ApiInterception/TC-0009-post-mocking/spec.md

@@ -10,3 +10,10 @@ coverage:
 ---
 
 # Mock and assert POST API requests using browser.intercept
+
+## Test Steps
+1. Open API POST section in matchers page
+2. Intercept POST /api/posts with mock response returning 201 status
+3. Fill post title and post body inputs from fixture
+4. Click submit POST button
+5. Assert status badge displays 201 Created and response JSON contains new title

package/templates/default/specs/ApiInterception/TC-0009-post-mocking/web.test.ts

@@ -1,10 +1,12 @@
-it("should mock POST API submission using browser.intercept and verify created response", async () => {
+it("Mock and assert POST API requests using browser.intercept", async () => {
   // Navigate to API POST section
   await MatchersPage.open("api-post");
 
-  // Setup POST API interception with status 201
-  await browser.intercept(
-    "/api/posts",
+  // Setup POST API interception with status 201 — the app posts to the demo server's own
+  // self-hosted endpoint (/api/posts), no external network involved.
+  Spectra.clearMocks();
+  await Spectra.intercept(
+    "api/posts",
     "POST",
     Fixture.apiData.mockPostResponse,
     { statusCode: 201 }

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

@@ -0,0 +1,30 @@
+it("Intercept a direct (immediate) response and a late (delayed) response using Fixture data", async () => {
+  await MatchersPage.open("api-fetch");
+
+  // The app fetches the self-hosted demo endpoint (/api/posts on web, the same path served by
+  // the demo server and reached through the device proxy on mobile) — no external network, so
+  // there's no upstream latency leaking into the "immediate" assertion below. On web, CDP's
+  // Fetch domain intercepts it; on Android, the device's global HTTP proxy routes it through the
+  // same worker-side mock engine. Neither platform needs the app, or this test, to know anything
+  // special about being under test.
+  Spectra.clearMocks();
+
+  // Direct (immediate) response — Fixture data returned with no artificial latency.
+  const mock = await Spectra.intercept("api/posts", "GET", Fixture.apiData.mockPosts);
+  await MatchersPage.fetchApiButton.click();
+  await MatchersPage.fetchStatusBadge.shouldHaveText("200 OK");
+  await MatchersPage.fetchedItems.shouldHaveLength(Fixture.apiData.mockPosts.length);
+  await MatchersPage.fetchedItems.first().shouldContainText(Fixture.apiData.mockPosts[0].title);
+
+  // 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 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", { timeoutMs: 3500 });
+  await MatchersPage.fetchedItems.shouldHaveLength(Fixture.apiData.mockPosts.length, { timeoutMs: 3500 });
+});

package/templates/default/specs/ApiInterception/TC-0012-direct-and-late-response/spec.md

@@ -0,0 +1,22 @@
+---
+id: TC-0012-direct-and-late-response
+title: Intercept a direct (immediate) response and a late (delayed) response using Fixture data
+priority: High
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+  mobile: automated
+---
+
+# Intercept a direct (immediate) response and a late (delayed) response using Fixture data
+
+## Test Steps
+1. Open the API fetch section in the matchers page
+2. Intercept GET /api/posts with mock posts fixture data
+3. Click the fetch API button
+4. Assert the status badge displays 200 OK and the immediate fixture items render
+5. Update the mock response with an artificial 50ms delay
+6. Click the fetch API button
+7. Assert the loading indicator is visible while the request is held
+8. Assert the status badge displays 200 OK and the delayed fixture items render

package/templates/default/specs/ApiInterception/TC-0013-real-network-call-recorded/common.test.ts

@@ -0,0 +1,27 @@
+it("Make a genuine (non-intercepted) network call and verify it is recorded", async () => {
+  await MatchersPage.open("api-fetch");
+
+  // Deliberately no Spectra.intercept() call — this is a genuine request that actually leaves
+  // the app and hits a real server, not a mock. It targets the demo server's own self-hosted
+  // endpoint (started with `--demo`) instead of an external public API, so it's deterministic
+  // and fast everywhere. On web the browser reaches localhost directly; on Android it's
+  // transparently routed through the device's global HTTP proxy with no matching mock rule, so
+  // the worker's proxy just forwards it for real. Clear any mock a previous test in this suite
+  // left registered (e.g. against /api/posts) so it can't accidentally catch this request too —
+  // this test uses a different resource (/api/todos/1) specifically to avoid that collision,
+  // plus a cache-busting query param so a repeat run doesn't get a 304 Not Modified from the
+  // device/browser's own HTTP cache.
+  Spectra.clearMocks();
+  const cacheBuster = Date.now();
+  await MatchersPage.fetchCustomUrlInput.type(`http://localhost:5200/api/todos/1?cb=${cacheBuster}`);
+  await MatchersPage.fetchApiButton.click();
+  await MatchersPage.fetchStatusBadge.shouldHaveText("200 OK");
+
+  const entry = Spectra.browser.recordedNetwork.find((e) => e.url.includes(`todos/1?cb=${cacheBuster}`));
+  if (!entry) {
+    throw new Error("Expected a recorded network entry for the real demo-server call, found none");
+  }
+  if (entry.status !== 200) {
+    throw new Error(`Expected recorded entry status 200, got ${entry.status}`);
+  }
+});

package/templates/default/specs/ApiInterception/TC-0013-real-network-call-recorded/spec.md

@@ -0,0 +1,20 @@
+---
+id: TC-0013-real-network-call-recorded
+title: Make a genuine (non-intercepted) network call and verify it is recorded
+priority: High
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+  mobile: automated
+---
+
+# Make a genuine (non-intercepted) network call and verify it is recorded
+
+## Test Steps
+1. Open the API fetch section in the matchers page
+2. Clear any active mocks left by a previous test
+3. Enter a real (non-intercepted) demo-server todo endpoint URL with a cache-busting query param
+4. Click the fetch API button
+5. Assert the status badge displays 200 OK
+6. Assert the network report records the genuine call with status 200

package/templates/default/specs/ApiInterception/TC-0015-mock-server-sent-events/spec.md

@@ -0,0 +1,24 @@
+---
+id: TC-0015-mock-server-sent-events
+title: Mock a Server-Sent Events (EventSource) stream via the existing network-intercept engine
+priority: Medium
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+  mobile: unsupported
+---
+
+# Mock a Server-Sent Events (EventSource) stream via the existing network-intercept engine
+
+Mobile coverage is `unsupported`: React Native has no built-in `EventSource` — a real project
+targeting mobile would add a userland SSE client library, at which point whether/how it's
+mockable depends entirely on that library's own networking implementation, not something
+TestSpectra's driver can generalize over.
+
+## Test Steps
+1. Open the SSE matcher section
+2. Intercept GET /api/sse-feed with a text/event-stream mock body
+3. Click the connect button
+4. Assert two SSE messages render
+5. Assert the first message contains "hello from mock SSE" and the last contains "second event"

package/templates/default/specs/ApiInterception/TC-0015-mock-server-sent-events/web.test.ts

@@ -0,0 +1,26 @@
+it("Mock a Server-Sent Events (EventSource) stream via the existing network-intercept engine", async () => {
+  await MatchersPage.open("sse");
+
+  // EventSource's initial request is a plain HTTP GET under the hood — CDP's Fetch domain
+  // intercepts it exactly like any other fetch()/XHR request. Fulfilling it with a
+  // text/event-stream body delivers every "data: ...\n\n" block at once; the browser's own
+  // EventSource parser still splits that into individual "message" events and dispatches them
+  // just as it would for a real stream, which is the part this demo actually cares about.
+  //
+  // What this can't fake: `Fetch.fulfillRequest` delivers a complete, connection-closing
+  // response (there's no way to keep it open indefinitely the way a real SSE endpoint would), so
+  // the browser's EventSource treats that closure as a connection error shortly after — the
+  // events still arrive and get processed first, but the app's own "CONNECTED" status flips back
+  // to disconnected right after, same as it would after a real server unexpectedly closed the
+  // connection. So this test verifies the events were received, not that the connection stayed
+  // open — genuinely-persistent SSE isn't something a request/response-shaped mock can simulate.
+  await Spectra.intercept("/api/sse-feed", "GET", {
+    body: 'data: {"text":"hello from mock SSE"}\n\ndata: {"text":"second event"}\n\n',
+    headers: { "Content-Type": "text/event-stream" },
+  });
+
+  await Spectra.get("#sse-connect-btn").click();
+  await Spectra.getAll(".sse-message-item").shouldHaveLength(2);
+  await Spectra.getAll(".sse-message-item").first().shouldContainText("hello from mock SSE");
+  await Spectra.getAll(".sse-message-item").last().shouldContainText("second event");
+});

package/templates/default/specs/ApiInterception/TC-0016-bypass-websocket-with-app-level-mock/spec.md

@@ -0,0 +1,37 @@
+---
+id: TC-0016-bypass-websocket-with-app-level-mock
+title: Bypass a real WebSocket connection via an app-level test-only mock flag
+priority: Medium
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+  mobile: unsupported
+---
+
+# Bypass a real WebSocket connection via an app-level test-only mock flag
+
+**Why this isn't network-level interception like `Spectra.intercept()`:** a WebSocket connection
+starts as an HTTP `Upgrade` handshake and then becomes a raw bidirectional frame stream — it's
+never a single request/response CDP's `Fetch` domain can fulfill the way it fulfills a normal
+`fetch()`/`XHR`/`EventSource` request. Chrome DevTools Protocol's WebSocket-related events
+(`Network.webSocketCreated`, `webSocketFrameSent`/`webSocketFrameReceived`, etc.) are
+observation-only — CDP has no command that mocks or rewrites a WS frame in flight. This is a
+genuine protocol-level limitation, not a gap in this driver.
+
+The practical workaround, and what this demo shows: the app itself checks for a test-only global
+flag (`window.__mockWebSocketMessages`) and swaps in an in-memory fake socket when present,
+instead of opening a real connection. `Spectra.browser.evaluate()` sets that flag before the app
+connects. This is the same pattern used by Cypress/Playwright test suites for the same reason.
+
+Mobile coverage is `unsupported`: React Native's WebSocket implementation is a native module,
+not a page-context global reachable via a browser-style `evaluate()` call — a mobile equivalent
+would need the RN app's own WebSocket client wrapper to support a comparable test-only bypass.
+
+## Test Steps
+1. Open the WebSocket matcher section
+2. Set the app-level mock flag via browser.evaluate before the app connects
+3. Click the connect button
+4. Assert the connection status displays CONNECTED and two mocked frames render
+5. Click the disconnect button
+6. Assert the connection status displays DISCONNECTED

package/templates/default/specs/ApiInterception/TC-0016-bypass-websocket-with-app-level-mock/web.test.ts

@@ -0,0 +1,21 @@
+it("Bypass a real WebSocket connection via an app-level test-only mock flag", async () => {
+  await MatchersPage.open("websocket");
+
+  // Set BEFORE the app opens its connection — the component checks this flag inside its own
+  // connect() handler and, if present, uses an in-memory fake socket instead of a real
+  // `new WebSocket(...)`. This is necessarily app-level, not network-level: see this TC's
+  // spec.md for why CDP has no way to intercept/mock a WebSocket handshake or its frames the
+  // way Spectra.intercept() does for fetch()/XHR/EventSource.
+  await Spectra.browser.evaluate(
+    "window.__mockWebSocketMessages = ['hello from mock WS', 'second frame']",
+  );
+
+  await Spectra.get("#ws-connect-btn").click();
+  await Spectra.get("#ws-connection-status").shouldHaveText("CONNECTED");
+  await Spectra.getAll(".ws-message-item").shouldHaveLength(2);
+  await Spectra.getAll(".ws-message-item").first().shouldContainText("hello from mock WS");
+  await Spectra.getAll(".ws-message-item").last().shouldContainText("second frame");
+
+  await Spectra.get("#ws-disconnect-btn").click();
+  await Spectra.get("#ws-connection-status").shouldHaveText("DISCONNECTED");
+});

package/templates/default/specs/ApiInterception/TC-0017-bypass-captcha-with-test-mode-flag/spec.md

@@ -0,0 +1,29 @@
+---
+id: TC-0017-bypass-captcha-with-test-mode-flag
+title: Bypass a live reCAPTCHA widget via an app-level test-only flag
+priority: Medium
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+  mobile: unsupported
+---
+
+# Bypass a live reCAPTCHA widget via an app-level test-only flag
+
+Real reCAPTCHA renders inside a cross-origin iframe (`google.com`), which Google explicitly
+discourages driving via browser automation — there's no `Spectra.intercept()`-style network mock
+for a live third-party widget's challenge/response flow. The demo embeds the real widget (site key
+`6LcWK4QtAAAAAAeA8IAN20JceGQ7L-RWE-LfhZnB`) for visual completeness, but the test itself uses the
+same pattern real projects use in CI: an app-level `window.__bypassCaptcha` flag the submit
+handler honors instead of ever attempting to automate the actual challenge.
+
+Mobile coverage is `unsupported`: a native captcha SDK (rather than a page-context script tag)
+would need its own test-only bypass hook, which is outside what a generic web-style demo can show.
+
+## Test Steps
+1. Open the captcha matcher section
+2. Click submit without the bypass flag and assert the widget refuses
+3. Set the app-level bypass flag via browser.evaluate
+4. Click submit again
+5. Assert the submission message indicates the form was bypassed for automated testing

package/templates/default/specs/ApiInterception/TC-0017-bypass-captcha-with-test-mode-flag/web.test.ts

@@ -0,0 +1,16 @@
+it("Bypass a live reCAPTCHA widget via an app-level test-only flag", async () => {
+  await MatchersPage.open("captcha");
+
+  // Baseline: without the flag (and no completed challenge), the widget refuses to submit —
+  // proving the success below is specifically driven by the bypass flag, not a stale state.
+  await Spectra.get("#captcha-submit-btn").click();
+  await Spectra.get("#captcha-submit-message").shouldContainText("complete the reCAPTCHA challenge");
+
+  // Set BEFORE submitting — see this TC's spec.md for why this has to be an app-level bypass
+  // rather than a network-level mock (real reCAPTCHA lives in a cross-origin iframe with no
+  // request/response Spectra.intercept() could fulfill).
+  await Spectra.browser.evaluate("window.__bypassCaptcha = true");
+
+  await Spectra.get("#captcha-submit-btn").click();
+  await Spectra.get("#captcha-submit-message").shouldContainText("bypassed for automated test");
+});

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

@@ -7,3 +7,4 @@ parallel: true
 ---
 
 # Suite: ApiInterception
+

package/templates/default/specs/ApiSeeding/TC-0014-seed-and-cleanup-via-hooks/common.test.ts

@@ -0,0 +1,30 @@
+// The `before` hook (hooks/before/common.hook.ts) already ran by the time this test body
+// executes — it seeded a post via a real POST to the demo server's self-hosted API and stashed
+// the result on globalThis for this test to read. Cleanup (hooks/after/common.hook.ts) runs
+// after this whole suite finishes, so it can't be observed from inside the suite's own tests —
+// a separate monitoring suite/run would be how a real project verifies cleanup actually happened.
+//
+// Suite-scoped hooks only run when a worker's whole batch is unambiguously scoped to this one
+// suite (e.g. `spectra run specs/ApiSeeding` or targeting this TC directly) — hook functions are
+// process-global singleton slots, not per-test-case, so a worker batch spanning multiple suites
+// has no correct way to scope suite A's hooks to only run around suite A's own tests, and skips
+// suite-level hooks entirely rather than risk applying the wrong suite's hooks to the wrong
+// tests. Running the FULL default template (`spectra run -t web`/`android`, every suite at once)
+// will legitimately fail this specific test for that reason — that's an inherent limitation of
+// the current worker-batching model, not a bug in this demo.
+it("Verify test data seeded by a before hook via the demo server's self-hosted API is available to the test", async () => {
+  const seeding = (globalThis as any).__apiSeeding;
+
+  if (!seeding?.seededPost) {
+    throw new Error("Expected the before hook to have seeded a post onto globalThis.__apiSeeding, found none");
+  }
+  if (typeof seeding.seededPost.id !== "number") {
+    throw new Error(`Expected seeded post to have a numeric id, got ${JSON.stringify(seeding.seededPost.id)}`);
+  }
+  if (seeding.seededPost.title !== "TestSpectra seeded post") {
+    throw new Error(`Expected seeded post title to match, got "${seeding.seededPost.title}"`);
+  }
+  if (seeding.cleanedUp !== false) {
+    throw new Error("Expected cleanedUp to still be false — the after hook hasn't run yet at this point");
+  }
+});