test: add unit and integration tests for moz-extension:// navigation fix

Author: csamu

src/firefox/pages.ts

@@ -7,7 +7,11 @@ import { log, logDebug } from '../utils/logger.js';
 
 const PRIVILEGED_URL_SCHEMES = ['moz-extension:'];
 
-function isPrivilegedUrl(url: string): boolean {
+/**
+ * Check if a URL uses a privileged scheme that requires BiDi navigation.
+ * @internal Exported for testability only; not a stable public API.
+ */
+export function isPrivilegedUrl(url: string): boolean {
   try {
     return PRIVILEGED_URL_SCHEMES.includes(new URL(url).protocol);
   } catch {

tests/firefox/pages.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Unit tests for PageManagement and isPrivilegedUrl
+ *
+ * The moz-extension:// fix: geckodriver's driver.get() hangs on extension URLs
+ * because it waits for BiDi navigation completion events that the Remote Agent
+ * never emits for extension contexts. The fix routes moz-extension:// URLs
+ * through BiDi browsingContext.navigate with wait:"none", which returns
+ * immediately without waiting for load events.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { isPrivilegedUrl, PageManagement } from '@/firefox/pages.js';
+
+// -- isPrivilegedUrl ----------------------------------------------------------
+
+describe('isPrivilegedUrl', () => {
+  it('returns true for moz-extension:// URLs', () => {
+    expect(isPrivilegedUrl('moz-extension://abc123/popup.html')).toBe(true);
+  });
+
+  it('returns false for https:// URLs', () => {
+    expect(isPrivilegedUrl('https://example.com')).toBe(false);
+  });
+
+  it('returns false for http:// URLs', () => {
+    expect(isPrivilegedUrl('http://localhost:3000')).toBe(false);
+  });
+
+  it('returns false for file:// URLs', () => {
+    expect(isPrivilegedUrl('file:///path/to/page.html')).toBe(false);
+  });
+
+  it('returns false for about: URLs (not in PRIVILEGED_URL_SCHEMES)', () => {
+    expect(isPrivilegedUrl('about:blank')).toBe(false);
+  });
+
+  // Malformed strings make URL constructor throw; the catch block returns false
+  it('returns false for malformed URLs', () => {
+    expect(isPrivilegedUrl('not-a-url')).toBe(false);
+  });
+
+  it('returns false for empty string', () => {
+    expect(isPrivilegedUrl('')).toBe(false);
+  });
+});
+
+// -- PageManagement -----------------------------------------------------------
+
+describe('PageManagement', () => {
+  type BiDiCommandFn = (method: string, params: Record<string, any>) => Promise<any>;
+
+  /**
+   * Build mocked PageManagement dependencies.
+   *
+   * The contextId handling is subtle: null and undefined mean different things.
+   * - contextId: null   → explicitly null (no browsing context available)
+   * - contextId omitted → defaults to 'ctx-1' (normal case)
+   *
+   * We use `'contextId' in overrides` to distinguish these, because
+   * `null ?? 'ctx-1'` would incorrectly collapse null into the default.
+   */
+  function createMocks(overrides?: { contextId?: string | null; sendBiDiCommand?: BiDiCommandFn }) {
+    const driver = { get: vi.fn().mockResolvedValue(undefined) } as any;
+    const hasContextId = 'contextId' in (overrides ?? {});
+    const contextId = hasContextId ? overrides!.contextId : 'ctx-1';
+    const getCurrentContextId = vi.fn().mockImplementation(() => contextId);
+    const setCurrentContextId = vi.fn();
+
+    // When sendBiDiCommand is provided, wrap it in a mock so we can assert calls.
+    // When omitted, it stays undefined — simulates BiDi being unavailable.
+    const sendBiDiCommand = overrides?.sendBiDiCommand
+      ? vi.fn().mockImplementation(overrides.sendBiDiCommand)
+      : undefined;
+
+    const pages = new PageManagement(driver, getCurrentContextId, setCurrentContextId, sendBiDiCommand as any);
+    return { pages, driver, getCurrentContextId, setCurrentContextId, sendBiDiCommand: sendBiDiCommand as any };
+  }
+
+  describe('navigate', () => {
+    // Core fix: moz-extension:// must use BiDi, not driver.get()
+    it('uses BiDi browsingContext.navigate with wait:none for moz-extension:// URLs', async () => {
+      const bidiFn = vi.fn().mockResolvedValue({});
+      const { pages, driver, sendBiDiCommand } = createMocks({ sendBiDiCommand: bidiFn });
+
+      await pages.navigate('moz-extension://abc123/popup.html');
+
+      expect(sendBiDiCommand).toHaveBeenCalledWith('browsingContext.navigate', {
+        context: 'ctx-1',
+        url: 'moz-extension://abc123/popup.html',
+        wait: 'none',
+      });
+      expect(driver.get).not.toHaveBeenCalled();
+    });
+
+    // Guard: no context ID means we can't send a BiDi command.
+    // Also verify sendBiDiCommand was never called (not just that it threw).
+    it('throws when context ID is null for moz-extension:// URL', async () => {
+      const bidiFn = vi.fn().mockResolvedValue({});
+      const { pages, sendBiDiCommand } = createMocks({ contextId: null, sendBiDiCommand: bidiFn });
+
+      await expect(pages.navigate('moz-extension://abc123/popup.html')).rejects.toThrow(
+        'Cannot navigate to privileged URL moz-extension://abc123/popup.html: no browsing context ID'
+      );
+      expect(sendBiDiCommand).not.toHaveBeenCalled();
+    });
+
+    // Fallback: if BiDi is not available (e.g. no Remote Agent), we still try
+    // driver.get(). This will hang for moz-extension://, but there's no alternative.
+    it('falls through to driver.get() for moz-extension:// when BiDi is unavailable', async () => {
+      const { pages, driver, sendBiDiCommand } = createMocks();
+
+      await pages.navigate('moz-extension://abc123/popup.html');
+
+      expect(driver.get).toHaveBeenCalledWith('moz-extension://abc123/popup.html');
+      expect(sendBiDiCommand).toBeUndefined();
+    });
+
+    // Non-privileged URLs always use the standard path
+    it('uses driver.get() for normal URLs', async () => {
+      const bidiFn = vi.fn().mockResolvedValue({});
+      const { pages, driver, sendBiDiCommand } = createMocks({ sendBiDiCommand: bidiFn });
+
+      await pages.navigate('https://example.com');
+
+      expect(driver.get).toHaveBeenCalledWith('https://example.com');
+      expect(sendBiDiCommand).not.toHaveBeenCalled();
+    });
+
+    // If the BiDi command rejects, the error should propagate (no silent swallow)
+    it('propagates BiDi navigation errors for moz-extension:// URLs', async () => {
+      const bidiFn = vi.fn().mockRejectedValue(new Error('BiDi error: invalid context'));
+      const { pages } = createMocks({ sendBiDiCommand: bidiFn });
+
+      await expect(pages.navigate('moz-extension://abc123/popup.html')).rejects.toThrow(
+        'BiDi error: invalid context'
+      );
+    });
+  });
+
+  describe('createNewPage', () => {
+    // createNewPage must delegate to navigate(), not call driver.get() directly,
+    // so that the moz-extension:// BiDi path is also used for new tabs
+    it('uses BiDi navigate for moz-extension:// URL after creating the tab', async () => {
+      const bidiFn = vi.fn().mockResolvedValue({});
+      const allHandles = ['handle-1', 'handle-2'];
+      const driver = {
+        get: vi.fn().mockResolvedValue(undefined),
+        switchTo: vi.fn().mockReturnValue({ newWindow: vi.fn().mockResolvedValue(undefined) }),
+        getAllWindowHandles: vi.fn().mockResolvedValue(allHandles),
+      } as any;
+      const getCurrentContextId = vi.fn().mockReturnValue('handle-2');
+      const setCurrentContextId = vi.fn();
+
+      const pages = new PageManagement(driver, getCurrentContextId, setCurrentContextId, bidiFn as any);
+
+      const idx = await pages.createNewPage('moz-extension://abc123/popup.html');
+
+      // Verify the BiDi navigate was used (not driver.get)
+      expect(bidiFn).toHaveBeenCalledWith('browsingContext.navigate', {
+        context: 'handle-2',
+        url: 'moz-extension://abc123/popup.html',
+        wait: 'none',
+      });
+      // Verify context was set before navigation
+      expect(setCurrentContextId).toHaveBeenCalledWith('handle-2');
+      expect(driver.get).not.toHaveBeenCalled();
+      expect(idx).toBe(1);
+    });
+
+    // With a normal URL, createNewPage delegates to navigate() which uses driver.get()
+    it('uses driver.get() for normal URLs after creating the tab', async () => {
+      const bidiFn = vi.fn().mockResolvedValue({});
+      const allHandles = ['handle-1', 'handle-2'];
+      const driver = {
+        get: vi.fn().mockResolvedValue(undefined),
+        switchTo: vi.fn().mockReturnValue({ newWindow: vi.fn().mockResolvedValue(undefined) }),
+        getAllWindowHandles: vi.fn().mockResolvedValue(allHandles),
+      } as any;
+      const getCurrentContextId = vi.fn().mockReturnValue('handle-2');
+      const setCurrentContextId = vi.fn();
+
+      const pages = new PageManagement(driver, getCurrentContextId, setCurrentContextId, bidiFn as any);
+
+      const idx = await pages.createNewPage('https://example.com');
+
+      expect(driver.get).toHaveBeenCalledWith('https://example.com');
+      expect(bidiFn).not.toHaveBeenCalled();
+      expect(idx).toBe(1);
+    });
+  });
+});

tests/fixtures/test-extension/manifest.json

@@ -0,0 +1,9 @@
+{
+  "manifest_version": 2,
+  "name": "MCP Test Extension",
+  "version": "1.0",
+  "description": "Minimal extension for testing moz-extension:// navigation",
+  "browser_action": {
+    "default_popup": "popup.html"
+  }
+}

tests/fixtures/test-extension/popup.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>MCP Test Extension</title>
+</head>
+<body>
+  <h1>MCP Test Extension</h1>
+  <p id="status">extension-loaded</p>
+</body>
+</html>

tests/integration/moz-extension.integration.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Integration tests for moz-extension:// navigation
+ * Tests with real Firefox browser in headless mode
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { createTestFirefox, closeFirefox, waitFor } from '../helpers/firefox.js';
+import type { FirefoxClient } from '@/firefox/index.js';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { unlinkSync, existsSync } from 'node:fs';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const fixturesPath = resolve(__dirname, '../fixtures');
+const extensionDir = resolve(fixturesPath, 'test-extension');
+const xpiPath = resolve(fixturesPath, 'test-extension.xpi');
+
+function packExtension(): void {
+  // Remove stale .xpi so zip creates a fresh archive
+  if (existsSync(xpiPath)) {
+    unlinkSync(xpiPath);
+  }
+  // Use execFileSync to avoid shell interpolation of paths
+  execFileSync('zip', ['-j', xpiPath, 'manifest.json', 'popup.html'], {
+    cwd: extensionDir,
+    stdio: 'pipe',
+  });
+}
+
+/**
+ * Get the moz-extension:// hostname for an installed extension by switching
+ * to a chrome-privileged context and querying WebExtensionPolicy.
+ * Requires MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1.
+ */
+async function getExtensionHostname(firefox: FirefoxClient, extensionId: string): Promise<string> {
+  const treeResult = await firefox.sendBiDiCommand('browsingContext.getTree', {
+    'moz:scope': 'chrome',
+  });
+  const contexts = treeResult.contexts || [];
+  if (contexts.length === 0) {
+    throw new Error('No chrome contexts available');
+  }
+
+  const driver = firefox.getDriver();
+  const originalContextId = firefox.getCurrentContextId();
+  const chromeContextId = contexts[0].context;
+
+  try {
+    await driver.switchTo().window(chromeContextId);
+    await driver.setContext('chrome');
+
+    const hostname = await driver.executeAsyncScript(`
+      const callback = arguments[arguments.length - 1];
+      const extensionId = ${JSON.stringify(extensionId)};
+      (async () => {
+        try {
+          const policy = WebExtensionPolicy.getByID(extensionId);
+          callback(policy ? policy.mozExtensionHostname : '');
+        } catch { callback(''); }
+      })();
+    `);
+
+    if (!hostname) {
+      throw new Error(
+        `Could not resolve hostname for extension ${extensionId}, got: ${JSON.stringify(hostname)}`
+      );
+    }
+    return hostname as string;
+  } finally {
+    try {
+      await driver.setContext('content');
+      if (originalContextId) {
+        await driver.switchTo().window(originalContextId);
+      }
+    } catch (e) {
+      console.warn('Failed to restore context after getExtensionHostname:', e);
+    }
+  }
+}
+
+describe('moz-extension:// Navigation Integration Tests', () => {
+  let firefox: FirefoxClient;
+  let extensionUrl: string;
+  let extensionId: string;
+
+  beforeAll(async () => {
+    packExtension();
+
+    // MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1 is required to resolve the extension hostname
+    firefox = await createTestFirefox({
+      env: { MOZ_REMOTE_ALLOW_SYSTEM_ACCESS: '1' },
+    });
+
+    // Install the test extension
+    const installResult = await firefox.sendBiDiCommand('webExtension.install', {
+      extensionData: { type: 'archivePath', path: xpiPath },
+    });
+    extensionId = installResult?.extension;
+    if (!extensionId) {
+      throw new Error(`Extension install returned no ID, got: ${JSON.stringify(installResult)}`);
+    }
+
+    // Resolve the moz-extension:// URL from the extension hostname
+    const hostname = await getExtensionHostname(firefox, extensionId);
+    extensionUrl = `moz-extension://${hostname}/popup.html`;
+  }, 60000);
+
+  afterAll(async () => {
+    // Uninstall the test extension to avoid accumulation across test runs
+    if (extensionId) {
+      try {
+        await firefox.sendBiDiCommand('webExtension.uninstall', { extension: extensionId });
+      } catch {}
+    }
+    await closeFirefox(firefox);
+    // Remove the packed .xpi so no build artifact remains on disk
+    if (existsSync(xpiPath)) {
+      unlinkSync(xpiPath);
+    }
+  });
+
+  it('should navigate to moz-extension:// URL without hanging', async () => {
+    // Before the fix, driver.get() would hang indefinitely because geckodriver
+    // waits for BiDi navigation completion events that the Remote Agent does
+    // not emit for extension contexts.
+    // wait:"none" returns in milliseconds, so a 5s timeout proves no hang
+    // while tolerating slow CI.
+    const result = await Promise.race([
+      firefox.navigate(extensionUrl).then(() => 'navigated'),
+      new Promise<string>((resolve) =>
+        setTimeout(() => resolve('timeout'), 5000)
+      ),
+    ]);
+
+    expect(result).toBe('navigated');
+
+    // Poll for the page URL since wait:none returns before the page loads
+    const driver = firefox.getDriver();
+    await waitFor(async () => {
+      const url = await driver.getCurrentUrl();
+      return url.includes('moz-extension://');
+    }, 5000);
+
+    // Verify the extension page content actually loaded
+    const title = await driver.getTitle();
+    expect(title).toBe('MCP Test Extension');
+  }, 15000);
+
+  it('should create new page with moz-extension:// URL without hanging', async () => {
+    const result = await Promise.race([
+      firefox.createNewPage(extensionUrl).then((idx: number) => `created-${idx}`),
+      new Promise<string>((resolve) =>
+        setTimeout(() => resolve('timeout'), 5000)
+      ),
+    ]);
+
+    expect(result).toMatch(/^created-/);
+
+    // Poll for the page URL since wait:none returns before the page loads
+    const driver = firefox.getDriver();
+    await waitFor(async () => {
+      const url = await driver.getCurrentUrl();
+      return url.includes('moz-extension://');
+    }, 5000);
+
+    // Verify the extension page content actually loaded
+    const title = await driver.getTitle();
+    expect(title).toBe('MCP Test Extension');
+  }, 15000);
+});