selenium-webext-bridge 0.1.0

package/extension/direct-bridge.js

@@ -0,0 +1,211 @@
+/**
+ * Direct Bridge - Content script that relays messages between page and background
+ */
+
+console.log('[DIRECT BRIDGE] Initializing...');
+
+// Inject TestBridge API into page
+const script = document.createElement('script');
+script.textContent = `
+(function() {
+  console.log('[DIRECT BRIDGE] Creating API in page context...');
+
+  let requestId = 0;
+  const pendingRequests = new Map();
+
+  // Listen for responses from content script via postMessage
+  window.addEventListener('message', (event) => {
+    if (event.source !== window) return;
+    if (event.data && event.data.type === 'bridge-response') {
+      const { id, response, error } = event.data;
+      const { resolve, reject } = pendingRequests.get(id) || {};
+      if (resolve) {
+        pendingRequests.delete(id);
+        if (error) reject(new Error(error));
+        else resolve(response);
+      }
+    }
+  });
+
+  // Send request to content script via postMessage
+  function sendRequest(action, data) {
+    return new Promise((resolve, reject) => {
+      const id = ++requestId;
+      pendingRequests.set(id, { resolve, reject });
+      window.postMessage({ type: 'bridge-request', id, action, data }, '*');
+      // Timeout after 15 seconds (some ops like waitForTabUrl can take a while)
+      setTimeout(() => {
+        if (pendingRequests.has(id)) {
+          pendingRequests.delete(id);
+          reject(new Error('Request timed out'));
+        }
+      }, 15000);
+    });
+  }
+
+  window.TestBridge = {
+    // --- Basics ---
+    async ping() {
+      return await sendRequest('ping');
+    },
+
+    // --- Tab Queries ---
+    async getTabs() {
+      return await sendRequest('getTabs');
+    },
+    async getTabById(tabId) {
+      return await sendRequest('getTabById', { tabId });
+    },
+    async getTabGroups() {
+      return await sendRequest('getTabGroups');
+    },
+
+    // --- Tab Lifecycle ---
+    async createTab(url, active) {
+      return await sendRequest('createTab', { url, active });
+    },
+    async closeTab(tabId) {
+      return await sendRequest('closeTab', { tabId });
+    },
+    async updateTab(tabId, props) {
+      return await sendRequest('updateTab', { tabId, ...props });
+    },
+
+    // --- Tab State ---
+    async moveTab(tabId, index) {
+      return await sendRequest('moveTab', { tabId, index });
+    },
+    async pinTab(tabId) {
+      return await sendRequest('pinTab', { tabId });
+    },
+    async unpinTab(tabId) {
+      return await sendRequest('unpinTab', { tabId });
+    },
+    async groupTabs(tabIds, title, color, groupId) {
+      return await sendRequest('groupTabs', { tabIds, title, color: color || 'blue', groupId });
+    },
+    async ungroupTabs(tabIds) {
+      return await sendRequest('ungroupTabs', { tabIds });
+    },
+    async muteTab(tabId) {
+      return await sendRequest('muteTab', { tabId });
+    },
+    async unmuteTab(tabId) {
+      return await sendRequest('unmuteTab', { tabId });
+    },
+    async reloadTab(tabId) {
+      return await sendRequest('reloadTab', { tabId });
+    },
+    async getActiveTab() {
+      return await sendRequest('getActiveTab');
+    },
+
+    // --- Tab Waiting ---
+    async waitForTabUrl(pattern, timeout) {
+      return await sendRequest('waitForTabUrl', { pattern, timeout });
+    },
+    async waitForCondition(conditionFn, timeout) {
+      timeout = timeout || 5000;
+      const start = Date.now();
+      while (Date.now() - start < timeout) {
+        if (await conditionFn()) return true;
+        await new Promise(r => setTimeout(r, 100));
+      }
+      return false;
+    },
+
+    // --- Execute in Tab ---
+    async executeInTab(tabId, code) {
+      return await sendRequest('executeInTab', { tabId, code });
+    },
+
+    // --- Screenshots ---
+    async captureScreenshot(format) {
+      return await sendRequest('captureScreenshot', { format });
+    },
+
+    // --- Window Management ---
+    async createWindow(url, options) {
+      return await sendRequest('createWindow', { url, ...options });
+    },
+    async closeWindow(windowId) {
+      return await sendRequest('closeWindow', { windowId });
+    },
+    async getWindows() {
+      return await sendRequest('getWindows');
+    },
+    async getWindowById(windowId) {
+      return await sendRequest('getWindowById', { windowId });
+    },
+    async updateWindow(windowId, props) {
+      return await sendRequest('updateWindow', { windowId, ...props });
+    },
+
+    // --- Tab Events ---
+    async getTabEvents(clear) {
+      return await sendRequest('getTabEvents', { clear });
+    },
+
+    // --- Window Events ---
+    async getWindowEvents(clear) {
+      return await sendRequest('getWindowEvents', { clear });
+    },
+
+    // --- Extension Forwarding ---
+    async forwardToExtension(targetExtensionId, payload) {
+      return await sendRequest('forwardToExtension', { targetExtensionId, payload });
+    }
+  };
+
+  console.log('[DIRECT BRIDGE] API ready');
+})();
+`;
+document.documentElement.appendChild(script);
+script.remove();
+
+// All actions that route through the background script
+const BG_ACTIONS = new Set([
+  'getTabs', 'getTabGroups', 'moveTab', 'pinTab', 'unpinTab',
+  'muteTab', 'unmuteTab', 'reloadTab', 'getActiveTab',
+  'groupTabs', 'ungroupTabs', 'forwardToExtension',
+  'createTab', 'closeTab', 'getTabById', 'updateTab',
+  'waitForTabUrl', 'executeInTab', 'captureScreenshot',
+  'createWindow', 'closeWindow', 'getWindows', 'getWindowById',
+  'updateWindow', 'getTabEvents', 'getWindowEvents'
+]);
+
+// Listen for requests from page via postMessage
+window.addEventListener('message', async (event) => {
+  // Only accept messages from same window
+  if (event.source !== window) return;
+  if (!event.data || event.data.type !== 'bridge-request') return;
+
+  const { id, action, data } = event.data;
+
+  try {
+    let response;
+
+    if (action === 'ping') {
+      response = 'pong';
+    } else if (BG_ACTIONS.has(action)) {
+      // Route through background script
+      const bgResponse = await browser.runtime.sendMessage({ action, ...data });
+      if (bgResponse && bgResponse.success) {
+        response = bgResponse.data;
+      } else if (bgResponse && bgResponse.error) {
+        throw new Error(bgResponse.error);
+      } else {
+        response = bgResponse;
+      }
+    } else {
+      throw new Error('Unknown action: ' + action);
+    }
+
+    window.postMessage({ type: 'bridge-response', id, response }, '*');
+  } catch (error) {
+    console.error('[DIRECT BRIDGE] Error:', error);
+    window.postMessage({ type: 'bridge-response', id, error: error.message }, '*');
+  }
+});
+
+console.log('[DIRECT BRIDGE] Ready');

package/extension/manifest.json

@@ -0,0 +1,37 @@
+{
+  "manifest_version": 2,
+  "name": "Selenium WebExt Bridge",
+  "version": "1.0.0",
+  "description": "Test bridge extension for automated testing of Firefox WebExtensions",
+
+  "browser_specific_settings": {
+    "gecko": {
+      "id": "selenium-webext-bridge@test.local"
+    }
+  },
+
+  "permissions": [
+    "tabs",
+    "tabGroups",
+    "storage",
+    "<all_urls>"
+  ],
+
+  "background": {
+    "scripts": ["background.js"]
+  },
+
+  "content_scripts": [
+    {
+      "matches": ["<all_urls>"],
+      "js": ["direct-bridge.js"],
+      "run_at": "document_idle",
+      "all_frames": false
+    }
+  ],
+
+  "web_accessible_resources": [
+    "test-api.html",
+    "test-api.js"
+  ]
+}

package/extension/test-api.html

@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <title>Selenium WebExt Bridge</title>
+    <style>
+        body {
+            font-family: monospace;
+            padding: 20px;
+            background: #1e1e1e;
+            color: #d4d4d4;
+        }
+        h1 {
+            color: #4ec9b0;
+        }
+        .status {
+            padding: 10px;
+            margin: 10px 0;
+            border-radius: 4px;
+            background: #2d2d2d;
+        }
+        .ready {
+            border-left: 4px solid #4ec9b0;
+        }
+        .error {
+            border-left: 4px solid #f48771;
+        }
+        pre {
+            background: #252525;
+            padding: 10px;
+            border-radius: 4px;
+            overflow-x: auto;
+        }
+        code {
+            color: #ce9178;
+        }
+    </style>
+</head>
+<body>
+    <h1>Selenium WebExt Bridge</h1>
+    <div id="status" class="status">
+        <strong>Status:</strong> <span id="status-text">Initializing...</span>
+    </div>
+
+    <h2>Usage from Selenium:</h2>
+    <pre><code>// Navigate to this page
+await driver.get('moz-extension://&lt;uuid&gt;/test-api.html');
+
+// Call API methods
+const tabs = await driver.executeScript(() => {
+    return window.TestBridge.getTabs();
+});
+
+// Forward messages to your extension
+const state = await driver.executeScript(() => {
+    return window.TestBridge.forwardToExtension('your-ext@id', { action: 'getState' });
+});</code></pre>
+
+    <h2>Available Methods:</h2>
+    <div id="methods"></div>
+
+    <script src="test-api.js"></script>
+</body>
+</html>

package/extension/test-api.js

@@ -0,0 +1,150 @@
+/**
+ * Selenium WebExt Bridge API - Exposed to Selenium tests
+ */
+
+console.log('[BRIDGE API] Initializing...');
+
+// Helper: send message to background and unwrap response
+async function bgCall(msg) {
+  const response = await browser.runtime.sendMessage(msg);
+  if (!response.success) throw new Error(response.error);
+  return response.data;
+}
+
+// Create the API that Selenium will call
+window.TestBridge = {
+  // --- Basics ---
+  async ping() {
+    return await bgCall({ action: 'ping' });
+  },
+
+  // --- Tab Queries ---
+  async getTabs() {
+    return await bgCall({ action: 'getTabs' });
+  },
+  async getTabById(tabId) {
+    return await bgCall({ action: 'getTabById', tabId });
+  },
+  async getTabGroups() {
+    return await bgCall({ action: 'getTabGroups' });
+  },
+
+  // --- Tab Lifecycle ---
+  async createTab(url, active) {
+    return await bgCall({ action: 'createTab', url, active });
+  },
+  async closeTab(tabId) {
+    return await bgCall({ action: 'closeTab', tabId });
+  },
+  async updateTab(tabId, props) {
+    return await bgCall({ action: 'updateTab', tabId, ...props });
+  },
+
+  // --- Tab State ---
+  async moveTab(tabId, index) {
+    return await bgCall({ action: 'moveTab', tabId, index });
+  },
+  async pinTab(tabId) {
+    return await bgCall({ action: 'pinTab', tabId });
+  },
+  async unpinTab(tabId) {
+    return await bgCall({ action: 'unpinTab', tabId });
+  },
+  async groupTabs(tabIds, title, color = 'blue', groupId = null) {
+    return await bgCall({ action: 'groupTabs', tabIds, title, color, groupId });
+  },
+  async ungroupTabs(tabIds) {
+    return await bgCall({ action: 'ungroupTabs', tabIds });
+  },
+  async muteTab(tabId) {
+    return await bgCall({ action: 'muteTab', tabId });
+  },
+  async unmuteTab(tabId) {
+    return await bgCall({ action: 'unmuteTab', tabId });
+  },
+  async reloadTab(tabId) {
+    return await bgCall({ action: 'reloadTab', tabId });
+  },
+  async getActiveTab() {
+    return await bgCall({ action: 'getActiveTab' });
+  },
+
+  // --- Tab Waiting ---
+  async waitForTabUrl(pattern, timeout) {
+    return await bgCall({ action: 'waitForTabUrl', pattern, timeout });
+  },
+  async waitForCondition(conditionFn, timeout = 5000) {
+    const start = Date.now();
+    while (Date.now() - start < timeout) {
+      if (await conditionFn()) return true;
+      await new Promise(r => setTimeout(r, 100));
+    }
+    return false;
+  },
+
+  // --- Execute in Tab ---
+  async executeInTab(tabId, code) {
+    return await bgCall({ action: 'executeInTab', tabId, code });
+  },
+
+  // --- Screenshots ---
+  async captureScreenshot(format) {
+    return await bgCall({ action: 'captureScreenshot', format });
+  },
+
+  // --- Window Management ---
+  async createWindow(url, options) {
+    return await bgCall({ action: 'createWindow', url, ...options });
+  },
+  async closeWindow(windowId) {
+    return await bgCall({ action: 'closeWindow', windowId });
+  },
+  async getWindows() {
+    return await bgCall({ action: 'getWindows' });
+  },
+  async getWindowById(windowId) {
+    return await bgCall({ action: 'getWindowById', windowId });
+  },
+  async updateWindow(windowId, props) {
+    return await bgCall({ action: 'updateWindow', windowId, ...props });
+  },
+
+  // --- Tab Events ---
+  async getTabEvents(clear) {
+    return await bgCall({ action: 'getTabEvents', clear });
+  },
+
+  // --- Window Events ---
+  async getWindowEvents(clear) {
+    return await bgCall({ action: 'getWindowEvents', clear });
+  },
+
+  // --- Extension Forwarding ---
+  async forwardToExtension(targetExtensionId, payload) {
+    return await bgCall({ action: 'forwardToExtension', targetExtensionId, payload });
+  }
+};
+
+// Update UI with available methods
+document.addEventListener('DOMContentLoaded', async () => {
+  const statusText = document.getElementById('status-text');
+  const statusDiv = document.getElementById('status');
+  const methodsDiv = document.getElementById('methods');
+
+  try {
+    const pong = await window.TestBridge.ping();
+    statusText.textContent = `Ready! (${pong})`;
+    statusDiv.classList.add('ready');
+
+    const methods = Object.keys(window.TestBridge);
+    methodsDiv.innerHTML = '<ul>' +
+      methods.map(m => `<li><code>TestBridge.${m}()</code></li>`).join('') +
+      '</ul>';
+
+    console.log('[BRIDGE API] Ready!');
+  } catch (error) {
+    statusText.textContent = 'Error: ' + error.message;
+    statusDiv.classList.add('error');
+    console.error('[BRIDGE API] Error:', error);
+  }
+});

package/extension/uuid-injector.js

@@ -0,0 +1,56 @@
+/**
+ * UUID Injector Content Script
+ *
+ * Injects the test bridge extension UUID into every page so Selenium can find it
+ */
+
+(function() {
+    // Get our own extension UUID
+    const extensionURL = browser.runtime.getURL('test-api.html');
+    const uuidMatch = extensionURL.match(/moz-extension:\/\/([^\/]+)/);
+
+    if (!uuidMatch) {
+        console.error('[BRIDGE] Failed to extract UUID from:', extensionURL);
+        return;
+    }
+
+    const uuid = uuidMatch[1];
+
+    // CRITICAL: Content scripts run in an isolated world
+    // We need to inject into the page's actual context, not the content script context
+    // We do this by injecting a <script> tag that runs in the page context
+
+    function injectIntoPageContext() {
+        const script = document.createElement('script');
+        script.textContent = `
+            window.__TEST_BRIDGE_UUID = ${JSON.stringify(uuid)};
+            window.__TEST_BRIDGE_URL = ${JSON.stringify(extensionURL)};
+            console.log('[BRIDGE] UUID injected into page context:', ${JSON.stringify(uuid)});
+        `;
+
+        // Inject at the very beginning of document
+        if (document.documentElement) {
+            document.documentElement.appendChild(script);
+            script.remove(); // Clean up after injection
+        } else {
+            // If documentElement doesn't exist yet, wait
+            setTimeout(injectIntoPageContext, 10);
+        }
+    }
+
+    // Also create a meta tag marker
+    function injectMarker() {
+        if (document.head) {
+            const marker = document.createElement('meta');
+            marker.name = 'test-bridge-uuid';
+            marker.content = uuid;
+            document.head.appendChild(marker);
+        } else {
+            setTimeout(injectMarker, 10);
+        }
+    }
+
+    // Inject immediately
+    injectIntoPageContext();
+    injectMarker();
+})();

package/index.js

@@ -0,0 +1,19 @@
+const { TestBridge } = require('./lib/test-bridge');
+const { sleep, generateTestUrl, waitForCondition, TabUtils, Assert, TestResults, launchBrowser, cleanupBrowser, extensionDir } = require('./lib/test-helpers');
+const { createTestServer } = require('./lib/test-http-server');
+const { Command } = require('selenium-webdriver/lib/command');
+
+module.exports = {
+  TestBridge,
+  sleep,
+  generateTestUrl,
+  waitForCondition,
+  TabUtils,
+  Assert,
+  TestResults,
+  createTestServer,
+  launchBrowser,
+  cleanupBrowser,
+  extensionDir,
+  Command
+};