@arcadialdev/arcality 2.2.0

package/.agents/skills/playwright-best-practices/testing-patterns/browser-extensions.md

@@ -0,0 +1,506 @@
+# Browser Extension Testing
+
+## Table of Contents
+
+1. [Setup & Configuration](#setup--configuration)
+2. [Loading Extensions](#loading-extensions)
+3. [Popup Testing](#popup-testing)
+4. [Background Script Testing](#background-script-testing)
+5. [Content Script Testing](#content-script-testing)
+6. [Extension APIs](#extension-apis)
+7. [Cross-Browser Testing](#cross-browser-testing)
+
+## Setup & Configuration
+
+### Prerequisites
+
+```bash
+npm install -D @playwright/test
+npx playwright install chromium  # Extensions only work in Chromium
+```
+
+### Basic Configuration
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from "@playwright/test";
+import path from "path";
+
+export default defineConfig({
+  testDir: "./tests",
+  use: {
+    // Extensions require non-headless Chromium
+    headless: false,
+  },
+  projects: [
+    {
+      name: "chromium-extension",
+      use: {
+        browserName: "chromium",
+      },
+    },
+  ],
+});
+```
+
+### Extension Fixture
+
+```typescript
+// fixtures/extension.ts
+import { test as base, chromium, BrowserContext, Page } from "@playwright/test";
+import path from "path";
+
+type ExtensionFixtures = {
+  context: BrowserContext;
+  extensionId: string;
+  backgroundPage: Page;
+};
+
+export const test = base.extend<ExtensionFixtures>({
+  context: async ({}, use) => {
+    const pathToExtension = path.join(__dirname, "../extension");
+
+    const context = await chromium.launchPersistentContext("", {
+      headless: false,
+      args: [
+        `--disable-extensions-except=${pathToExtension}`,
+        `--load-extension=${pathToExtension}`,
+      ],
+    });
+
+    await use(context);
+    await context.close();
+  },
+
+  extensionId: async ({ context }, use) => {
+    // Get extension ID from service worker URL
+    let extensionId = "";
+
+    // Wait for service worker to be registered
+    const serviceWorker =
+      context.serviceWorkers()[0] ||
+      (await context.waitForEvent("serviceworker"));
+
+    extensionId = serviceWorker.url().split("/")[2];
+
+    await use(extensionId);
+  },
+
+  backgroundPage: async ({ context }, use) => {
+    // For Manifest V2 extensions
+    const backgroundPage =
+      context.backgroundPages()[0] ||
+      (await context.waitForEvent("backgroundpage"));
+
+    await use(backgroundPage);
+  },
+});
+
+export { expect } from "@playwright/test";
+```
+
+## Loading Extensions
+
+### Manifest V3 (Service Worker)
+
+```typescript
+test("load MV3 extension", async () => {
+  const pathToExtension = path.join(__dirname, "../my-extension");
+
+  const context = await chromium.launchPersistentContext("", {
+    headless: false,
+    args: [
+      `--disable-extensions-except=${pathToExtension}`,
+      `--load-extension=${pathToExtension}`,
+    ],
+  });
+
+  // Wait for service worker
+  const serviceWorker = await context.waitForEvent("serviceworker");
+  expect(serviceWorker.url()).toContain("chrome-extension://");
+
+  await context.close();
+});
+```
+
+### Manifest V2 (Background Page)
+
+```typescript
+test("load MV2 extension", async () => {
+  const pathToExtension = path.join(__dirname, "../my-extension-v2");
+
+  const context = await chromium.launchPersistentContext("", {
+    headless: false,
+    args: [
+      `--disable-extensions-except=${pathToExtension}`,
+      `--load-extension=${pathToExtension}`,
+    ],
+  });
+
+  // Wait for background page
+  const backgroundPage = await context.waitForEvent("backgroundpage");
+  expect(backgroundPage.url()).toContain("chrome-extension://");
+
+  await context.close();
+});
+```
+
+### Multiple Extensions
+
+```typescript
+test("load multiple extensions", async () => {
+  const extension1 = path.join(__dirname, "../extension1");
+  const extension2 = path.join(__dirname, "../extension2");
+
+  const context = await chromium.launchPersistentContext("", {
+    headless: false,
+    args: [
+      `--disable-extensions-except=${extension1},${extension2}`,
+      `--load-extension=${extension1},${extension2}`,
+    ],
+  });
+
+  // Both service workers should be available
+  await context.waitForEvent("serviceworker");
+  await context.waitForEvent("serviceworker");
+
+  expect(context.serviceWorkers().length).toBe(2);
+
+  await context.close();
+});
+```
+
+## Popup Testing
+
+### Opening Extension Popup
+
+```typescript
+test("test popup UI", async ({ context, extensionId }) => {
+  // Open popup directly by URL
+  const popupPage = await context.newPage();
+  await popupPage.goto(`chrome-extension://${extensionId}/popup.html`);
+
+  // Test popup interactions
+  await expect(popupPage.getByRole("heading")).toHaveText("My Extension");
+  await popupPage.getByRole("button", { name: "Enable" }).click();
+  await expect(popupPage.getByText("Enabled")).toBeVisible();
+});
+```
+
+### Popup State Persistence
+
+```typescript
+test("popup remembers state", async ({ context, extensionId }) => {
+  // First interaction
+  const popup1 = await context.newPage();
+  await popup1.goto(`chrome-extension://${extensionId}/popup.html`);
+  await popup1.getByRole("checkbox", { name: "Dark Mode" }).check();
+  await popup1.close();
+
+  // Reopen popup
+  const popup2 = await context.newPage();
+  await popup2.goto(`chrome-extension://${extensionId}/popup.html`);
+
+  // State should persist
+  await expect(
+    popup2.getByRole("checkbox", { name: "Dark Mode" }),
+  ).toBeChecked();
+});
+```
+
+### Popup Communication with Background
+
+```typescript
+test("popup sends message to background", async ({ context, extensionId }) => {
+  const popup = await context.newPage();
+  await popup.goto(`chrome-extension://${extensionId}/popup.html`);
+
+  // Set up listener for response
+  const responsePromise = popup.evaluate(() => {
+    return new Promise((resolve) => {
+      chrome.runtime.onMessage.addListener((message) => {
+        if (message.type === "RESPONSE") resolve(message.data);
+      });
+    });
+  });
+
+  // Click button that sends message
+  await popup.getByRole("button", { name: "Fetch Data" }).click();
+
+  // Verify response
+  const response = await responsePromise;
+  expect(response).toBeDefined();
+});
+```
+
+## Background Script Testing
+
+### Manifest V3 Service Worker
+
+```typescript
+test("service worker handles messages", async ({ context, extensionId }) => {
+  const page = await context.newPage();
+  await page.goto("https://example.com");
+
+  // Send message to service worker from page
+  const response = await page.evaluate(async (extId) => {
+    return new Promise((resolve) => {
+      chrome.runtime.sendMessage(extId, { type: "GET_STATUS" }, resolve);
+    });
+  }, extensionId);
+
+  expect(response).toEqual({ status: "active" });
+});
+```
+
+### Testing Background Logic
+
+```typescript
+test("background script logic", async ({ context }) => {
+  const serviceWorker =
+    context.serviceWorkers()[0] ||
+    (await context.waitForEvent("serviceworker"));
+
+  // Evaluate in service worker context
+  const result = await serviceWorker.evaluate(async () => {
+    // Access extension APIs
+    const storage = await chrome.storage.local.get("settings");
+    return storage;
+  });
+
+  expect(result.settings).toBeDefined();
+});
+```
+
+### Alarms and Timers
+
+```typescript
+test("alarm triggers correctly", async ({ context }) => {
+  const serviceWorker = await context.waitForEvent("serviceworker");
+
+  // Create alarm
+  await serviceWorker.evaluate(async () => {
+    await chrome.alarms.create("test-alarm", { delayInMinutes: 0.01 });
+  });
+
+  // Wait for alarm handler
+  await serviceWorker.evaluate(() => {
+    return new Promise<void>((resolve) => {
+      chrome.alarms.onAlarm.addListener((alarm) => {
+        if (alarm.name === "test-alarm") resolve();
+      });
+    });
+  });
+
+  // Verify alarm was handled (check side effects)
+  const wasHandled = await serviceWorker.evaluate(async () => {
+    const { alarmTriggered } = await chrome.storage.local.get("alarmTriggered");
+    return alarmTriggered;
+  });
+
+  expect(wasHandled).toBe(true);
+});
+```
+
+## Content Script Testing
+
+### Injected Content Script
+
+```typescript
+test("content script injects UI", async ({ context }) => {
+  const page = await context.newPage();
+  await page.goto("https://example.com");
+
+  // Wait for content script to inject elements
+  await expect(page.locator("#my-extension-widget")).toBeVisible();
+
+  // Interact with injected UI
+  await page.locator("#my-extension-widget button").click();
+  await expect(page.locator("#my-extension-widget .result")).toHaveText(
+    "Success",
+  );
+});
+```
+
+### Content Script Communication
+
+```typescript
+test("content script communicates with background", async ({
+  context,
+  extensionId,
+}) => {
+  const page = await context.newPage();
+  await page.goto("https://example.com");
+
+  // Trigger content script action
+  await page.locator("#my-extension-button").click();
+
+  // Wait for background response reflected in UI
+  await expect(page.locator("#my-extension-status")).toHaveText("Connected");
+});
+```
+
+### Page Modification Testing
+
+```typescript
+test("content script modifies page", async ({ context }) => {
+  const page = await context.newPage();
+  await page.goto("https://example.com");
+
+  // Verify content script modifications
+  const hasModification = await page.evaluate(() => {
+    // Check for injected styles
+    const styles = document.querySelectorAll('style[data-extension="my-ext"]');
+    return styles.length > 0;
+  });
+
+  expect(hasModification).toBe(true);
+
+  // Check DOM modifications
+  const modifiedElements = await page
+    .locator("[data-modified-by-extension]")
+    .count();
+  expect(modifiedElements).toBeGreaterThan(0);
+});
+```
+
+## Extension APIs
+
+### Storage API
+
+```typescript
+test("chrome.storage operations", async ({ context }) => {
+  const serviceWorker = await context.waitForEvent("serviceworker");
+
+  // Set storage
+  await serviceWorker.evaluate(async () => {
+    await chrome.storage.local.set({ key: "value", count: 42 });
+  });
+
+  // Get storage
+  const data = await serviceWorker.evaluate(async () => {
+    return await chrome.storage.local.get(["key", "count"]);
+  });
+
+  expect(data).toEqual({ key: "value", count: 42 });
+
+  // Test storage.sync
+  await serviceWorker.evaluate(async () => {
+    await chrome.storage.sync.set({ synced: true });
+  });
+
+  const syncData = await serviceWorker.evaluate(async () => {
+    return await chrome.storage.sync.get("synced");
+  });
+
+  expect(syncData.synced).toBe(true);
+});
+```
+
+### Tabs API
+
+```typescript
+test("chrome.tabs operations", async ({ context }) => {
+  const serviceWorker = await context.waitForEvent("serviceworker");
+
+  // Create a tab
+  const page = await context.newPage();
+  await page.goto("https://example.com");
+
+  // Query tabs from service worker
+  const tabs = await serviceWorker.evaluate(async () => {
+    return await chrome.tabs.query({ url: "*://example.com/*" });
+  });
+
+  expect(tabs.length).toBeGreaterThan(0);
+  expect(tabs[0].url).toContain("example.com");
+
+  // Send message to tab
+  await serviceWorker.evaluate(async (tabId) => {
+    await chrome.tabs.sendMessage(tabId, { type: "PING" });
+  }, tabs[0].id);
+});
+```
+
+### Context Menus
+
+```typescript
+test("context menu actions", async ({ context, extensionId }) => {
+  const serviceWorker = await context.waitForEvent("serviceworker");
+
+  // Create context menu
+  await serviceWorker.evaluate(async () => {
+    await chrome.contextMenus.create({
+      id: "test-menu",
+      title: "Test Action",
+      contexts: ["selection"],
+    });
+  });
+
+  // Simulate context menu click
+  const page = await context.newPage();
+  await page.goto("https://example.com");
+
+  // Select text
+  await page.evaluate(() => {
+    const range = document.createRange();
+    range.selectNodeContents(document.body.firstChild!);
+    window.getSelection()?.addRange(range);
+  });
+
+  // Trigger context menu action programmatically
+  await serviceWorker.evaluate(async () => {
+    // Simulate the click handler
+    chrome.contextMenus.onClicked.dispatch(
+      { menuItemId: "test-menu", selectionText: "selected text" },
+      { id: 1, url: "https://example.com" },
+    );
+  });
+});
+```
+
+### Permissions API
+
+```typescript
+test("request permissions", async ({ context, extensionId }) => {
+  const popup = await context.newPage();
+  await popup.goto(`chrome-extension://${extensionId}/popup.html`);
+
+  // Check current permissions
+  const hasPermission = await popup.evaluate(async () => {
+    return await chrome.permissions.contains({
+      origins: ["https://*.github.com/*"],
+    });
+  });
+
+  // Request new permission (will show prompt in real scenario)
+  // For testing, we check the request is made correctly
+  const permissionRequest = popup.evaluate(async () => {
+    try {
+      return await chrome.permissions.request({
+        origins: ["https://*.github.com/*"],
+      });
+    } catch (e) {
+      return false;
+    }
+  });
+
+  // In automated tests, permission prompts are typically auto-granted or mocked
+});
+```
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern                   | Problem               | Solution                                 |
+| ------------------------------ | --------------------- | ---------------------------------------- |
+| Testing in headless mode       | Extensions don't load | Use `headless: false`                    |
+| Not waiting for service worker | Race conditions       | Wait for `serviceworker` event           |
+| Hardcoding extension ID        | ID changes on reload  | Extract ID from service worker URL       |
+| Testing packed extensions only | Slow iteration        | Test unpacked during development         |
+| Ignoring MV3 differences       | Breaking changes      | Test both MV2 and MV3 if supporting both |
+
+## Related References
+
+- **Service Workers**: See [service-workers.md](../browser-apis/service-workers.md) for SW testing patterns
+- **Multi-Context**: See [multi-context.md](../advanced/multi-context.md) for popup handling
+- **Browser APIs**: See [browser-apis.md](../browser-apis/browser-apis.md) for permissions testing