pi-lean-dimension 0.1.0 → 0.2.0

package/node_modules/pi-lean-portal/__tests__/chromium-py-persistence.test.ts

@@ -1,203 +1,29 @@
-/**
- * Chromium-Py Cookie Persistence Integration Test — end-to-end validation
- * of Bug A (router loads storage state) and Bug B (plugin saves state on
- * re-navigate) for the Python adapter / chromium-py bridge.
- *
- * Uses a live Chromium browser via the Chromium-Py bridge against a local
- * HTTP test server that serves a page with a cookie-based consent dialog.
- *
- * The test:
- * 1. Navigates with a named profile — dialog visible
- * 2. Clicks "Accept All" — sets a consent cookie
- * 3. Navigates again with the same profile — dialog should NOT reappear
- *    because the bridge reuses the BrowserContext (so cookies survive), and
- *    `_persistState` saves the state to disk for cross-session persistence.
- *
- * Auto-skips the entire suite when Python/chromium-py prerequisites are
- * unavailable.
- */
-
-import { describe, it, expect, beforeAll, afterAll } from "vitest";
-import { resolve } from "node:path";
-import { existsSync } from "node:fs";
-import { spawnSync } from "node:child_process";
-
+import { describe, beforeAll, afterAll } from "vitest";
 import { PythonPluginAdapter } from "../backends/python-adapter.js";
-import {
-	startTestServer,
-	COOKIE_PERSISTENCE_HTML,
-} from "./helpers/test-server.js";
-import {
-	loadStorageState,
-	deleteStorageState,
-} from "../core/shared/storage-state.js";
-import { sessionManager } from "../core/shared/session-manager.js";
-
-// ─── Paths ──────────────────────────────────────────────────────────
-
-const BRIDGE_SCRIPT = resolve(__dirname, "../backends/chromium-py/bridge.py");
-const PYTHON_PATH = resolve(
-	__dirname,
-	"../backends/python-base/.venv/bin/python3",
-);
-
-// ─── Prerequisites check — skip gracefully if absent ────────────────
-
-const prerequisitesMet = (() => {
-	if (!existsSync(PYTHON_PATH)) return false;
-	if (!existsSync(BRIDGE_SCRIPT)) return false;
-	const result = spawnSync(PYTHON_PATH, ["--version"], {
-		stdio: "ignore",
-		timeout: 5_000,
-	});
-	if (result.status !== 0) return false;
-
-	// Quick check: can we import playwright?
-	const check = spawnSync(
-		PYTHON_PATH,
-		["-c", "import playwright; print('ok')"],
-		{ stdio: "pipe", timeout: 5_000 },
-	);
-	return check.status === 0 && check.stdout.toString().trim() === "ok";
-})();
-
-const describeIfAvailable = prerequisitesMet ? describe : describe.skip;
-
-// ─── Test fixture HTML (imported from shared helper) ───────────────
-// See ``COOKIE_PERSISTENCE_HTML`` in ``helpers/test-server.ts``.
-
-// ─── Test Server Setup (always runs, server is cheap to start/stop) ─
-
-let serverUrl: string;
-let stopServer: () => Promise<void>;
+import { createPyBackendTestHarness } from "./helpers/create-py-backend-harness.js";
+import { startCookiePersistenceServer } from "./helpers/test-server.js";
+import { runPersistenceSuite } from "./helpers/persistence-suite.js";
 
+const { bridgeScript, pythonPath, prerequisitesMet } =
+	createPyBackendTestHarness("chromium-py");
+let serverUrl: string, stopServer: () => Promise<void>;
 beforeAll(async () => {
-	const server = await startTestServer((req, res) => {
-		const url = new URL(req.url ?? "/", "http://localhost");
-		if (url.pathname === "/") {
-			res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-			res.end(COOKIE_PERSISTENCE_HTML);
-		} else {
-			res.writeHead(404, { "Content-Type": "text/html; charset=utf-8" });
-			res.end("404");
-		}
-	});
-	serverUrl = server.url;
-	stopServer = server.stop;
+	const s = await startCookiePersistenceServer();
+	serverUrl = s.url;
+	stopServer = s.stop;
 });
-
 afterAll(async () => {
 	await stopServer();
 });
-
-const NAV_TIMEOUT = 30_000;
-const TASK_ID = "chromium-py-persistence";
-
-// ═════════════════════════════════════════════════════════════════
-// Tests — only run if Chromium + Python prerequisites are met
-// ═════════════════════════════════════════════════════════════════
-
-describeIfAvailable(
-	"Chromium-Py cookie persistence across navigations",
-	() => {
-		const TEST_PROFILE = `chromium-py-persist-${Date.now()}`;
-
-		let plugin: PythonPluginAdapter;
-
-		beforeAll(async () => {
-			plugin = new PythonPluginAdapter("chromium-py-persist", {
-				bridgeScript: BRIDGE_SCRIPT,
-				pythonPath: PYTHON_PATH,
-			});
-			await plugin.init();
-		});
-
-		afterAll(async () => {
-			await plugin.cleanupAll().catch(() => {});
-			deleteStorageState(TEST_PROFILE);
-		});
-
-		it("navigates with a named profile — consent dialog is visible", async () => {
-			const nav = await plugin.navigate(serverUrl, TASK_ID, NAV_TIMEOUT, {
-				profileName: TEST_PROFILE,
-				profileMode: "named",
-			});
-			expect(nav.success).toBe(true);
-			expect(nav.title).toContain("Cookie Persistence Test");
-			expect(nav.snapshot).toContain("Consent");
-			expect(nav.snapshot).toContain("Accept All");
-		});
-
-		it("clicks Accept All — cookie set, consent dialog closes", async () => {
-			const snap = await plugin.snapshot(TASK_ID);
-			expect(snap.success).toBe(true);
-
-			// Find "Accept All" button in the snapshot and extract its @e ref
-			const btnMatch = snap.snapshot.match(/@(e\d+)\b.*?button.*?Accept All/);
-			expect(btnMatch).toBeTruthy();
-			if (!btnMatch) return;
-
-			const ref = `@${btnMatch[1]!}`;
-			const clickResult = await plugin.click(TASK_ID, ref);
-			expect(clickResult.success).toBe(true);
-
-			// Verify dialog is gone from snapshot
-			if (clickResult.snapshot) {
-				expect(clickResult.snapshot).not.toContain("Consent");
-			}
-		});
-
-		it("creates session and sets persistState (simulating the router's setup)", async () => {
-			sessionManager.createSession(TASK_ID, "chromium-py-persist");
-			const session = sessionManager.getSession(TASK_ID);
-			expect(session).toBeDefined();
-			if (session) {
-				session.persistState = true;
-				session.profileName = TEST_PROFILE;
-			}
-		});
-
-		it("navigates again with same profile — consent dialog does NOT reappear", async () => {
-			// This navigate triggers navigate() which:
-			//   1. Detects re-navigate (task already in _pages)
-			//   2. Calls _persistState → saves cookies to disk via getStorageState RPC
-			//   3. Sends browser.navigate RPC → bridge reuses existing context
-			// The cookie set during the previous click is still present in the
-			// reused BrowserContext, so the dialog should not reappear.
-			const nav = await plugin.navigate(serverUrl, TASK_ID, NAV_TIMEOUT, {
-				profileName: TEST_PROFILE,
-				profileMode: "named",
-			});
-			expect(nav.success).toBe(true);
-
-			// Consent dialog should NOT be present — cookies survived in-context
-			expect(nav.snapshot).not.toContain("Consent");
-			expect(nav.snapshot).not.toContain("Accept All");
-		});
-
-		it("storage-state.json exists on disk with the consent cookie", async () => {
-			const state = loadStorageState(TEST_PROFILE);
-			expect(state).not.toBeNull();
-			expect(state!.cookies.length).toBeGreaterThan(0);
-
-			const consentCookie = state!.cookies.find(
-				(c: { name: string; value: string }) =>
-					c.name === "consent" && c.value === "accepted",
-			);
-			expect(consentCookie).toBeDefined();
-		});
-
-		it("third navigate also has no consent dialog (persistence confirmed)", async () => {
-			const nav = await plugin.navigate(serverUrl, TASK_ID, NAV_TIMEOUT, {
-				profileName: TEST_PROFILE,
-				profileMode: "named",
-			});
-			expect(nav.success).toBe(true);
-
-			// Dialog should still be absent
-			expect(nav.snapshot).not.toContain("Consent");
-			expect(nav.snapshot).not.toContain("Accept All");
-		});
+runPersistenceSuite(prerequisitesMet ? describe : describe.skip, {
+	name: "chromium-py",
+	getServerUrl: () => serverUrl,
+	createPlugin: async () => {
+		const p = new PythonPluginAdapter("chromium-py-persist", {
+			bridgeScript,
+			pythonPath,
+		});
+		await p.init();
+		return p;
 	},
-	120_000,
-);
+});

package/node_modules/pi-lean-portal/__tests__/chromium-py.test.ts

@@ -1,87 +1,23 @@
-/**
- * Contract tests for the Chromium-Py backend — validates that the
- * PythonPluginAdapter + Chromium-Py bridge satisfies the BrowserPlugin
- * contract against a real browser.
- *
- * Phase B6: Test Chromium-Py against the contract harness.
- *
- * This test file instantiates a PythonPluginAdapter pointing at the
- * Chromium-Py bridge script and runs both structural and behavioral
- * contract tests.  The Python subprocess is managed by the adapter;
- * no manual setup is needed beyond having Playwright Chromium installed
- * in the Python virtual environment.
- *
- * Prerequisites:
- *   - Python venv at backends/python-base/.venv with playwright installed
- *   - Playwright Chromium browsers installed (playwright install chromium)
- */
-
-import { resolve } from "node:path";
-import { existsSync } from "node:fs";
-import { spawnSync } from "node:child_process";
-
 import { PythonPluginAdapter } from "../backends/python-adapter.js";
 import { runContractTests } from "./helpers/plugin-contract.js";
+import { createPyBackendTestHarness } from "./helpers/create-py-backend-harness.js";
 
-// ─── Paths ──────────────────────────────────────────────────────────
-
-const BRIDGE_SCRIPT = resolve(__dirname, "../backends/chromium-py/bridge.py");
-
-const PYTHON_PATH = resolve(
-	__dirname,
-	"../backends/python-base/.venv/bin/python3",
-);
-
-// ─── Environment check ───────────────────────────────────────────────
-
-const pythonAvailable = (() => {
-	if (!existsSync(PYTHON_PATH)) return false;
-	const result = spawnSync(PYTHON_PATH, ["--version"], {
-		stdio: "ignore",
-		timeout: 5_000,
-	});
-	return result.status === 0;
-})();
-
-const bridgeExists = existsSync(BRIDGE_SCRIPT);
-
-// ─── Plugin factory ─────────────────────────────────────────────────
-
-/**
- * Create a PythonPluginAdapter that drives the Chromium-Py bridge.
- *
- * The adapter is lazy — the Python subprocess won't start until the
- * first operation.  We pass the venv Python path so the bridge has
- * access to playwright and the shared pi_browser_bridge library.
- */
-function createChromiumPyPlugin(): PythonPluginAdapter {
-	return new PythonPluginAdapter("chromium-py", {
-		bridgeScript: BRIDGE_SCRIPT,
-		pythonPath: PYTHON_PATH,
-		// Chromium-Py supports everything except AbortSignal
-		capabilities: {
-			supportsFullPageScreenshot: true,
-			supportsConsoleCapture: true,
-			supportsJavaScriptEvaluate: true,
-			supportsBotDetection: true,
-			supportsDialogAutoDismissal: true,
-			supportsAbortSignal: false,
-			engine: "chromium",
-		},
-	});
-}
-
-// ─── Run contract tests ──────────────────────────────────────────────
-
-// Skip the entire suite if prerequisites aren't met (CI without
-// Playwright installed, local dev without venv, etc.)
-const describeIfAvailable =
-	pythonAvailable && bridgeExists ? describe : describe.skip;
+const { bridgeScript, pythonPath, describeIfAvailable } =
+	createPyBackendTestHarness("chromium-py");
 
 describeIfAvailable("Chromium-Py contract tests", () => {
-	runContractTests("chromium-py", createChromiumPyPlugin, {
-		realBrowser: true,
-		navigateTimeout: 30_000,
-		navigationSettle: true,
-	});
+	runContractTests(
+		"chromium-py",
+		() =>
+			new PythonPluginAdapter("chromium-py", {
+				bridgeScript,
+				pythonPath,
+				capabilities: {
+					supportsFullPageScreenshot: true,
+					supportsJavaScriptEvaluate: true,
+					engine: "chromium",
+				},
+			}),
+		{ realBrowser: true, navigateTimeout: 30_000, navigationSettle: true },
+	);
 });

package/node_modules/pi-lean-portal/__tests__/chromium.test.ts

@@ -0,0 +1,25 @@
+import { existsSync } from "node:fs";
+import { chromium } from "playwright";
+import { describe } from "vitest";
+import { runContractTests } from "./helpers/plugin-contract.js";
+import { ChromiumPlugin } from "../backends/chromium/index.js";
+
+const describeIfAvailable = (() => {
+	try {
+		return existsSync(chromium.executablePath()) ? describe : describe.skip;
+	} catch {
+		return describe.skip;
+	}
+})();
+
+describeIfAvailable(
+	"ChromiumPlugin contract tests",
+	() => {
+		runContractTests("chromium", () => new ChromiumPlugin(), {
+			realBrowser: true,
+			navigateTimeout: 30_000,
+			navigationSettle: true,
+		});
+	},
+	60_000,
+);

package/node_modules/pi-lean-portal/__tests__/contributed/invisible-py/invisible-py.test.ts

@@ -0,0 +1,299 @@
+/**
+ * Invisible-py-specific behavioral tests (user-backends stealth engine,
+ * pattern #2) — exercises lifecycle pattern #2, multi-context
+ * deadlock avoidance, and the back-nav referrer workaround.
+ *
+ * The shared BrowserPlugin contract suite for invisible-py runs via
+ * `run-contributed-suites.test.ts` (`CONTRIB_RUN=1`). This file adds
+ * assertions unique to pattern #2 that the generic suite cannot cover.
+ *
+ * This is the **only** test suite that exercises lifecycle pattern #2
+ * (engine owns its own Playwright instance via `_ensure_playwright` /
+ * `_maybe_stop_playwright`).  Camoufox uses pattern #1 (accepts an
+ * external Playwright), so this suite serves as the unique probe for
+ * the pattern-#2 code path.
+ *
+ * Prerequisites (all auto-detected via probeUserBackend):
+ *   - `~/.pi/agent/pi-lean-portal/user-backends/invisible-py/bridge.py`
+ *     exists on disk.
+ *   - `.venv/bin/python3` runs and has `invisible_playwright` installed.
+ *   - Patched Firefox binary is fetched and runnable.
+ *
+ * Auto-skips the entire suite when prerequisites are absent.
+ *
+ * Assertions:
+ *   - **Pattern #2 lifecycle no-leak** — init/navigate/cleanupAll then
+ *     init/navigate again proves `_maybe_stop_playwright` actually tears
+ *     down the InvisiblePlaywright context manager and a second init
+ *     doesn't spawn a second Playwright instance.
+ *   - **Multi-context no-deadlock** — two sessions created concurrently
+ *     both navigate successfully, validating the `_capture_user_agent =
+ *     False` workaround that prevents the patched Firefox binary from
+ *     leaking implicit BrowserContexts.
+ *   - **Back-nav honest limitation** — `goBack()` after a link click
+ *     succeeds via the `document.referrer` workaround; `goBack()` after
+ *     a direct navigation (no referrer) returns `success: false` with
+ *     the documented limitation error.
+ *
+ * @module
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+
+import { PythonPluginAdapter } from "../../../backends/python-adapter.js";
+import { startTestServer } from "../../helpers/test-server.js";
+
+import { probeUserBackend } from "../../helpers/probe-user-backend.js";
+
+// ─── Prerequisites check via probeUserBackend ──────────────────────
+
+const probe = probeUserBackend("invisible-py");
+
+const invisiblePyAvailable = probe.available;
+
+// ─── Plugin factory ─────────────────────────────────────────────────
+
+/**
+ * Create a PythonPluginAdapter that drives the invisible-py bridge
+ * from the user-backends directory.
+ *
+ * The adapter is lazy — the Python subprocess won't start until the
+ * first operation.  Capabilities advertise `engine: "firefox"` because
+ * invisible-py wraps a patched Firefox binary.
+ */
+function createInvisiblePyPlugin(): PythonPluginAdapter {
+	return new PythonPluginAdapter("invisible-py", {
+		bridgeScript: probe.bridgePath,
+		pythonPath: probe.venvPython,
+		capabilities: {
+			supportsFullPageScreenshot: true,
+			supportsJavaScriptEvaluate: true,
+			engine: "firefox",
+		},
+	});
+}
+
+// ─── Test Server Setup (used for invisible-py-specific tests) ────────
+
+const PAGE_A_HTML = `<!DOCTYPE html>
+<html><head><title>Page A</title></head>
+<body>
+  <h1>Page A</h1>
+  <p>This is page A.</p>
+  <a href="/page-b" id="link-to-b">Go to Page B</a>
+</body></html>`;
+
+const PAGE_B_HTML = `<!DOCTYPE html>
+<html><head><title>Page B</title></head>
+<body>
+  <h1>Page B</h1>
+  <p>You reached page B via a link from page A.</p>
+  <a href="/direct-nav" id="link-to-direct">Go to Direct Nav</a>
+</body></html>`;
+
+const DIRECT_NAV_HTML = `<!DOCTYPE html>
+<html><head><title>Direct Nav Page</title></head>
+<body>
+  <h1>Direct Navigation Page</h1>
+  <p>Navigated here directly, no referrer.</p>
+</body></html>`;
+
+const SIMPLE_HTML = `<!DOCTYPE html>
+<html><head><title>Simple Page</title></head>
+<body><h1>Simple</h1></body></html>`;
+
+const MULTI_CONTEXT_HTML = `<!DOCTYPE html>
+<html><head><title>Multi Context Test</title></head>
+<body><h1>Multi Context Test Page</h1>
+<p id="marker">Session marker: loading complete.</p></body></html>`;
+
+let serverUrl: string;
+let stopServer: () => Promise<void>;
+
+beforeAll(async () => {
+	const server = await startTestServer((req, res) => {
+		const url = new URL(req.url ?? "/", "http://localhost");
+		switch (url.pathname) {
+			case "/page-a":
+				res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+				res.end(PAGE_A_HTML);
+				break;
+			case "/page-b":
+				res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+				res.end(PAGE_B_HTML);
+				break;
+			case "/direct-nav":
+				res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+				res.end(DIRECT_NAV_HTML);
+				break;
+			case "/simple":
+				res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+				res.end(SIMPLE_HTML);
+				break;
+			case "/multi-context":
+				res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+				res.end(MULTI_CONTEXT_HTML);
+				break;
+			default:
+				res.writeHead(404, { "Content-Type": "text/html; charset=utf-8" });
+				res.end("404");
+		}
+	});
+	serverUrl = server.url;
+	stopServer = server.stop;
+});
+
+afterAll(async () => {
+	await stopServer();
+});
+
+const describeIfAvailable = invisiblePyAvailable ? describe : describe.skip;
+
+describeIfAvailable("Invisible-Py contract tests", () => {
+	// ── Invisible-py-specific assertions ────────────────────────
+	//
+	// These go beyond the generic contract suite to exercise
+	// architecture-under-test features unique to pattern-#2 backends.
+
+	describe("Invisible-py-specific behaviors", () => {
+		let plugin: PythonPluginAdapter;
+
+		// Each test in this block runs with its own browser sessions.
+		// The patched Firefox binary limits concurrent BrowserContexts
+		// to ~2 per InvisiblePlaywright instance, so we tear down and
+		// re-init between tests to prevent session leaks — otherwise
+		// a test that creates 2 sessions blocks the next test's first
+		// navigate from creating a third context.
+		beforeEach(async () => {
+			plugin = createInvisiblePyPlugin();
+			await plugin.init();
+		});
+
+		afterEach(async () => {
+			await plugin.cleanupAll().catch(() => {});
+		});
+
+		// ── Pattern #2 lifecycle: no Playwright leak across cycles ─
+
+		it("pattern #2 lifecycle: init→navigate→cleanupAll→init→navigate succeeds without leak", async () => {
+			// Long timeout: two init cycles + two 30s navigations + cleanupAll.
+			// Each individual navigate call has a 30s timeout, so the test
+			// itself needs 60s+ to accommodate both cycles plus bridge ops.
+			// First cycle
+			const nav1 = await plugin.navigate(
+				`${serverUrl}/simple`,
+				"lifecycle-cycle-1",
+				30_000,
+			);
+			expect(nav1.success).toBe(true);
+			expect(nav1.title).toContain("Simple Page");
+
+			// Full teardown
+			await plugin.cleanupAll();
+
+			// Second cycle — init again (must not leak a Playwright instance)
+			await plugin.init();
+
+			const nav2 = await plugin.navigate(
+				`${serverUrl}/simple`,
+				"lifecycle-cycle-2",
+				30_000,
+			);
+			expect(nav2.success).toBe(true);
+			expect(nav2.title).toContain("Simple Page");
+		}, 120_000);
+
+		// ── Multi-context no-deadlock ─────────────────────────────
+		//
+		// Validates the `_capture_user_agent = False` workaround that
+		// prevents the patched Firefox binary from leaking implicit
+		// BrowserContexts.  Two independent sessions must both navigate
+		// without hanging.
+
+		it("multi-context: two independent sessions both navigate without deadlock", async () => {
+			// Long timeout: two sequential 30s navigations on a patched
+			// binary that may be slower than stock. 90s keeps the budget
+			// comfortable while still failing fast on a real deadlock.
+			const navA = await plugin.navigate(
+				`${serverUrl}/multi-context`,
+				"multi-context-a",
+				30_000,
+			);
+			expect(navA.success).toBe(true);
+			expect(navA.title).toContain("Multi Context Test");
+
+			const navB = await plugin.navigate(
+				`${serverUrl}/multi-context`,
+				"multi-context-b",
+				30_000,
+			);
+			expect(navB.success).toBe(true);
+			expect(navB.title).toContain("Multi Context Test");
+		}, 90_000);
+
+		// ── Back-nav honest limitation ───────────────────────────
+		//
+		// invisible-py wraps a patched Firefox binary that disables
+		// bfcache. Standard `page.go_back()` is non-functional. The
+		// bridge implements a `document.referrer` workaround that
+		// handles link-click → back scenarios but cannot handle
+		// direct navigations (no referrer).
+
+		it("goBack succeeds after a link click (referrer workaround)", async () => {
+			// Long timeout: navigate + snapshot + click + snapshot + goBack
+			// + snapshot — six bridge round-trips on a slow binary.
+			// Navigate to page A
+			const navA = await plugin.navigate(
+				`${serverUrl}/page-a`,
+				"back-ref-a",
+				30_000,
+			);
+			expect(navA.success).toBe(true);
+			expect(navA.title).toContain("Page A");
+
+			// Click the link to page B
+			const snapA = await plugin.snapshot("back-ref-a");
+			expect(snapA.success).toBe(true);
+
+			const linkMatch = snapA.snapshot.match(/@(e\d+)\b.*?link.*?Go to Page B/);
+			expect(linkMatch).toBeTruthy();
+			if (!linkMatch) return;
+
+			const ref = `@${linkMatch[1]!}`;
+			const clickResult = await plugin.click("back-ref-a", ref);
+			expect(clickResult.success).toBe(true);
+
+			// Verify we're on page B
+			const snapB = await plugin.snapshot("back-ref-a");
+			expect(snapB.snapshot).toContain("Page B");
+
+			// Go back via referrer workaround
+			const backResult = await plugin.goBack("back-ref-a");
+			expect(backResult.success).toBe(true);
+
+			// Verify we're back on page A
+			const snapAfterBack = await plugin.snapshot("back-ref-a");
+			expect(snapAfterBack.snapshot).toContain("Page A");
+		}, 90_000);
+
+		it("goBack after a direct navigation returns success: false (limitation)", async () => {
+			// navigate + goBack — two bridge calls, each may be slow.
+			// Navigate directly (no link click, no referrer)
+			const nav = await plugin.navigate(
+				`${serverUrl}/direct-nav`,
+				"back-direct",
+				30_000,
+			);
+			expect(nav.success).toBe(true);
+			expect(nav.title).toContain("Direct Nav Page");
+
+			// Attempt goBack — should fail because there's no referrer
+			const backResult = await plugin.goBack("back-direct");
+			expect(backResult.success).toBe(false);
+
+			// Should include a descriptive error message about the limitation
+			expect(typeof backResult.error).toBe("string");
+			expect((backResult.error as string).length).toBeGreaterThan(0);
+		}, 60_000);
+	});
+});