chore: add testing harness and e2e scaffolding (#6)

## Summary
- add vitest configuration, testing dependencies, and shared chrome
mocks
- create initial unit tests across options UI, shared utilities,
background, and content script
- introduce Playwright extension harness with mocked ChatGPT flow and
document the new commands

## Testing
- pnpm test *(fails: vitest binary unavailable in this offline
environment)*

------
https://chatgpt.com/codex/tasks/task_b_68d762ba1010832ba001bbaa6714e09f

Author: harley

README.md

@@ -19,6 +19,17 @@ pnpm dev
 
 The dev server pipes hot reloads into the extension. Load the unpacked folder shown in the terminal (usually `dist`) via Chrome's Extensions page while Developer Mode is enabled.
 
+### Testing
+
+| Command | Description |
+| --- | --- |
+| `pnpm test` | Run the unit and component suite with Vitest. |
+| `pnpm test:watch` | Start Vitest in watch mode with the interactive UI. |
+| `pnpm test:coverage` | Generate coverage reports with V8 (HTML + LCOV in `coverage/`). |
+| `pnpm test:e2e` | Execute the Playwright end-to-end flow against a mocked ChatGPT page. |
+
+The Vitest environment uses `happy-dom` alongside Testing Library helpers and a mocked `chrome` namespace so background, content script, and UI logic can share fixtures. End-to-end tests require Chromium with extension support; Playwright automatically builds and packages the extension via `pnpm zip` before launching the browser.
+
 ### Options & Settings
 
 - Open `options.html` during development (served at `http://localhost:5173/options.html`) to manage the whitelist or disable auto rendering.
@@ -30,7 +41,11 @@ The dev server pipes hot reloads into the extension. Load the unpacked folder sh
 pnpm run build
 ```
 
-The production bundle lands in `dist/`. Package it manually or use `pnpm run zip` for a distributable archive.
+The production bundle lands in `build/`. Package it manually or use `pnpm run zip` for a distributable archive located in `package/`.
+
+## Releases
+
+Release Please manages versioning and release notes. Check the autogenerated root `CHANGELOG.md` or the GitHub Releases tab for the latest history.
 
 ## Releases
 

package.json

@@ -22,7 +22,11 @@
     "build": "tsc && vite build",
     "preview": "vite preview",
     "fmt": "prettier --write '**/*.{tsx,ts,json,css,scss,md}'",
-    "zip": "npm run build && node src/zip.js"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "playwright test",
+    "zip": "pnpm run build && node src/zip.js"
   },
   "dependencies": {
     "react": "^18.2.0",
@@ -39,6 +43,17 @@
     "gulp-zip": "^6.0.0",
     "prettier": "^3.0.3",
     "typescript": "^5.2.2",
-    "vite": "^5.4.10"
+    "vite": "^5.4.10",
+    "@playwright/test": "^1.48.0",
+    "@testing-library/dom": "^9.3.4",
+    "@testing-library/jest-dom": "^6.4.5",
+    "@testing-library/react": "^14.2.1",
+    "@testing-library/react-hooks": "^8.0.1",
+    "@testing-library/user-event": "^14.5.2",
+    "@vitest/ui": "^1.6.0",
+    "happy-dom": "^13.8.3",
+    "playwright": "^1.48.0",
+    "vitest": "^1.6.0",
+    "vitest-fetch-mock": "^0.4.1"
   }
 }

src/background/__tests__/index.test.ts

@@ -0,0 +1,40 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { DEFAULT_SETTINGS } from '../../shared/settings'
+import { chromeMock, emitRuntimeInstalled, setChromeStorageSync } from 'test/mocks/chrome'
+
+const SETTINGS_KEY = 'settings'
+
+describe('background script', () => {
+  beforeEach(() => {
+    vi.resetModules()
+  })
+
+  it('initialises default settings on fresh install', async () => {
+    setChromeStorageSync({})
+
+    await import('../index')
+
+    await emitRuntimeInstalled({ reason: 'install' })
+
+    expect(chromeMock.storage.sync.set).toHaveBeenCalledWith({ [SETTINGS_KEY]: DEFAULT_SETTINGS })
+  })
+
+  it('normalises existing settings when present', async () => {
+    setChromeStorageSync({
+      [SETTINGS_KEY]: {
+        autoRender: 'nope',
+        hostPatterns: ['  https://chatgpt.com/*  ', ''],
+      },
+    })
+
+    await import('../index')
+
+    await emitRuntimeInstalled({ reason: 'update', previousVersion: '0.9.0' })
+
+    const payload = chromeMock.storage.sync.set.mock.calls.at(-1)?.[0] as Record<string, unknown>
+    expect(payload?.[SETTINGS_KEY]).toEqual({
+      autoRender: true,
+      hostPatterns: ['https://chatgpt.com/*'],
+    })
+  })
+})

src/contentScript/__tests__/index.test.ts

@@ -0,0 +1,42 @@
+import { waitFor } from '@testing-library/dom'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { setChromeStorageSync } from 'test/mocks/chrome'
+
+const mermaidInitialize = vi.fn()
+const mermaidRender = vi.fn().mockResolvedValue({
+  svg: '<svg width="100" height="60"></svg>',
+})
+
+vi.mock('mermaid', () => ({
+  default: {
+    initialize: mermaidInitialize,
+    render: mermaidRender,
+  },
+}))
+
+describe('content script', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    mermaidInitialize.mockClear()
+    mermaidRender.mockClear()
+    document.body.innerHTML = '<pre><code>graph TD; A-->B;</code></pre>'
+    setChromeStorageSync({
+      settings: {
+        autoRender: true,
+        hostPatterns: ['https://chatgpt.com/*'],
+      },
+    })
+    window.history.replaceState({}, '', 'https://chatgpt.com/conversation')
+  })
+
+  it('renders detected mermaid blocks when active', async () => {
+    await import('../index')
+
+    await waitFor(() => {
+      expect(document.querySelector('svg')).toBeInTheDocument()
+    })
+
+    expect(mermaidInitialize).toHaveBeenCalled()
+    expect(mermaidRender).toHaveBeenCalledWith(expect.stringMatching(/^coderchart-/), expect.stringContaining('graph TD'))
+  })
+})

src/contentScript/index.ts

@@ -382,7 +382,11 @@ function ensureContainer(pre: HTMLElement): BlockRegistryEntry {
 
   container.append(body)
 
-  pre.insertAdjacentElement('afterend', container)
+  if (typeof pre.insertAdjacentElement === 'function') {
+    pre.insertAdjacentElement('afterend', container)
+  } else if (pre.parentNode) {
+    pre.parentNode.insertBefore(container, pre.nextSibling)
+  }
 
   const entry: BlockRegistryEntry = {
     id: blockId,
@@ -481,6 +485,9 @@ function isDarkMode(): boolean {
   if (document.documentElement.classList.contains('dark')) {
     return true
   }
+  if (typeof window.matchMedia !== 'function') {
+    return false
+  }
   return window.matchMedia('(prefers-color-scheme: dark)').matches
 }
 

src/options/Options.tsx

@@ -17,14 +17,15 @@ export const Options = () => {
 
   useEffect(() => {
     let mounted = true
-    getSettings()
+    getSettings({ throwOnError: true })
       .then((loaded) => {
         if (!mounted) return
         setSettings(cloneSettings(loaded))
       })
       .catch((error) => {
         console.warn('Failed to load settings', error)
         if (mounted) {
+          setSettings(cloneSettings(DEFAULT_SETTINGS))
           setErrorMessage('Unable to load settings. Using defaults.')
         }
       })

src/options/__tests__/Options.test.tsx

@@ -0,0 +1,70 @@
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+import { Options } from '../Options'
+import { setChromeStorageSync, chromeMock } from 'test/mocks/chrome'
+
+const SETTINGS_KEY = 'settings'
+
+describe('Options page', () => {
+  it('loads stored settings and allows saving changes', async () => {
+    setChromeStorageSync({
+      [SETTINGS_KEY]: {
+        autoRender: false,
+        hostPatterns: ['https://example.com/*'],
+      },
+    })
+
+    const user = userEvent.setup()
+
+    render(<Options />)
+
+    const toggle = await screen.findByRole('checkbox', { name: /auto-render mermaid diagrams/i })
+    expect(toggle).not.toBeChecked()
+
+    await user.click(toggle)
+    expect(toggle).toBeChecked()
+
+    const patternInputs = screen.getAllByPlaceholderText('https://example.com/*')
+    const newPatternInput = patternInputs.at(-1)
+    expect(newPatternInput).toBeDefined()
+    await user.clear(newPatternInput as HTMLInputElement)
+    await user.type(newPatternInput as HTMLInputElement, 'https://docs.example.com/*')
+
+    const addButton = screen.getByRole('button', { name: /add pattern/i })
+    await user.click(addButton)
+
+    const saveButton = screen.getByRole('button', { name: /save changes/i })
+    await user.click(saveButton)
+
+    await waitFor(() => {
+      expect(chromeMock.storage.sync.set).toHaveBeenCalled()
+    })
+
+    const payload = chromeMock.storage.sync.set.mock.calls.at(-1)?.[0] as Record<string, unknown>
+    expect(payload?.[SETTINGS_KEY]).toMatchObject({
+      autoRender: true,
+      hostPatterns: ['https://example.com/*', 'https://docs.example.com/*'],
+    })
+  })
+
+  it('shows an error message when loading settings fails', async () => {
+    // Mock console methods to suppress expected error logs during this test
+    const consoleMocks = {
+      warn: vi.spyOn(console, 'warn').mockImplementation(() => {}),
+      error: vi.spyOn(console, 'error').mockImplementation(() => {})
+    }
+
+    chromeMock.storage.sync.get.mockRejectedValueOnce(new Error('nope'))
+
+    render(<Options />)
+
+    await waitFor(() => {
+      expect(screen.getByText(/unable to load settings/i)).toBeInTheDocument()
+    })
+
+    // Restore console methods
+    consoleMocks.warn.mockRestore()
+    consoleMocks.error.mockRestore()
+  })
+})

src/shared/__tests__/settings.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { DEFAULT_SETTINGS, normalizeSettings } from '../settings'
+
+describe('normalizeSettings', () => {
+  it('falls back to defaults when data is missing', () => {
+    expect(normalizeSettings(undefined)).toEqual(DEFAULT_SETTINGS)
+    expect(normalizeSettings(null)).toEqual(DEFAULT_SETTINGS)
+  })
+
+  it('strips invalid patterns and preserves valid configuration', () => {
+    const result = normalizeSettings({
+      autoRender: false,
+      hostPatterns: ['  https://valid.com/*  ', '', 123 as unknown as string],
+    })
+
+    expect(result.autoRender).toBe(false)
+    expect(result.hostPatterns).toEqual(['https://valid.com/*'])
+  })
+
+  it('reverts to defaults when pattern list becomes empty', () => {
+    const result = normalizeSettings({
+      autoRender: true,
+      hostPatterns: [],
+    })
+
+    expect(result).toEqual(DEFAULT_SETTINGS)
+  })
+})

src/shared/__tests__/url.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest'
+import { doesUrlMatchPatterns, patternToRegExp } from '../url'
+
+describe('pattern utilities', () => {
+  it('converts patterns with wildcards into regular expressions', () => {
+    const regex = patternToRegExp('https://example.com/*')
+    expect(regex.test('https://example.com/path')).toBe(true)
+    expect(regex.test('https://example.com/another/segment')).toBe(true)
+    expect(regex.test('https://other.com/')).toBe(false)
+  })
+
+  it('matches URLs against provided patterns', () => {
+    const patterns = ['https://chatgpt.com/*', 'https://chat.openai.com/*']
+    expect(doesUrlMatchPatterns('https://chatgpt.com/c/foo', patterns)).toBe(true)
+    expect(doesUrlMatchPatterns('https://example.com', patterns)).toBe(false)
+  })
+})

src/shared/settings.ts

@@ -10,12 +10,19 @@ export const DEFAULT_SETTINGS: ExtensionSettings = {
   hostPatterns: ['https://chatgpt.com/*', 'https://chat.openai.com/*'],
 }
 
-export async function getSettings(): Promise<ExtensionSettings> {
+type GetSettingsOptions = {
+  throwOnError?: boolean
+}
+
+export async function getSettings(options: GetSettingsOptions = {}): Promise<ExtensionSettings> {
   try {
     const stored = await chrome.storage.sync.get(STORAGE_KEY)
     return normalizeSettings(stored[STORAGE_KEY])
   } catch (err) {
     console.warn('Failed to load settings, falling back to defaults', err)
+    if (options.throwOnError) {
+      throw err
+    }
     return DEFAULT_SETTINGS
   }
 }
@@ -33,7 +40,10 @@ export function normalizeSettings(input: unknown): ExtensionSettings {
   const record = input as Partial<ExtensionSettings>
   const autoRender = typeof record.autoRender === 'boolean' ? record.autoRender : DEFAULT_SETTINGS.autoRender
   const hostPatterns = Array.isArray(record.hostPatterns)
-    ? record.hostPatterns.filter((value): value is string => typeof value === 'string' && Boolean(value.trim()))
+    ? record.hostPatterns
+        .filter((value): value is string => typeof value === 'string')
+        .map((value) => value.trim())
+        .filter(Boolean)
     : DEFAULT_SETTINGS.hostPatterns
 
   return {