binect-chrome/DEVELOPMENT.md

Development & Test-Fix Workflow for BinectChrome

This guide explains how to set up an efficient development workflow for testing and debugging the Chrome extension.

Quick Start

1. Development Mode (Auto-rebuild on changes)

npm run dev

This starts webpack in watch mode - any changes to source files will automatically rebuild the extension.

2. Load Extension in Chrome

Initial Load:

1. Open Chrome and navigate to chrome://extensions/
2. Enable "Developer mode" (toggle in top-right corner)
3. Click "Load unpacked"
4. Select the /home/worsch/binect-chrome/dist directory
5. Note the extension ID (you'll need this for debugging)

Reload After Changes:

• Option A (Manual): Click the reload icon on the extension card at chrome://extensions/
• Option B (Shortcut): Click the extensions icon in Chrome toolbar → Manage Extensions → Reload
• Option C (Recommended for service worker): Navigate to chrome://serviceworker-internals/ and click "Stop" then reload

3. Debug Service Worker

View Service Worker Logs:

1. Go to chrome://extensions/
2. Find your extension
3. Click "service worker" link (under "Inspect views")
4. This opens DevTools for the service worker

Alternative Method:

1. Go to chrome://serviceworker-internals/
2. Find "chrome-extension://[your-extension-id]"
3. Click "Inspect" to open DevTools

View Service Worker Status:

• chrome://serviceworker-internals/ - Shows all service workers, their status, and errors

4. Debug Popup & UI

Popup DevTools:

1. Click the extension icon to open the popup
2. Right-click inside the popup → "Inspect"
3. This opens DevTools for the popup

Tracking Page DevTools:

1. Open the tracking page from the popup
2. Right-click → "Inspect"

Complete Test-Fix Loop

Workflow Pattern

┌─────────────────────────────────────────────────┐
│  1. Make code changes in src/                   │
│  2. Webpack auto-rebuilds (if using npm run dev)│
│  3. Reload extension in Chrome                  │
│  4. Check DevTools for errors                   │
│  5. Test functionality                          │
│  6. Repeat from step 1                          │
└─────────────────────────────────────────────────┘

Detailed Steps

1. Start Development Mode

   npm run dev
   

2. Make Your Changes

   • Edit files in src/
   • Webpack will automatically rebuild

3. Reload Extension

   • Go to chrome://extensions/
   • Click reload icon on BinectChrome card
   • For service worker changes: Go to chrome://serviceworker-internals/ → Stop → Reload

4. Check for Errors

   • Service Worker: Click "service worker" link or check chrome://serviceworker-internals/
   • Popup: Right-click popup → Inspect
   • Console Errors: Check the browser console in all DevTools windows

5. Test Functionality

   • Download a PDF to test detection
   • Check badge updates
   • Test sending PDFs
   • Verify tracking data

6. Common Debugging Points

   • Service worker errors: Usually permissions or API usage issues
   • PDF detection not working: Check Downloads API events
   • Badge not updating: Check service worker is running
   • Alarms not firing: Check chrome://serviceworker-internals/ for service worker lifecycle

Common Issues & Solutions

Issue: Service Worker Registration Failed (Status Code 15)

Cause: Webpack output format doesn't match manifest type Solution: Ensure webpack.config.js has:

output: {
  module: true,
  environment: { module: true }
},
experiments: {
  outputModule: true
}

Issue: "Cannot read properties of undefined (reading 'onAlarm')"

Cause: Missing "alarms" permission Solution: Add to manifest.json:

"permissions": ["downloads", "storage", "alarms"]

Issue: Service Worker Stops Running

Cause: Chrome stops inactive service workers after 30 seconds (Manifest V3 behavior) Solution: This is normal! Service workers wake up on events (downloads, alarms, messages)

Issue: Changes Not Reflecting

Cause: Extension not reloaded, or cached service worker Solution:

1. Always reload after rebuilding
2. For stubborn issues: Stop service worker at chrome://serviceworker-internals/
3. Hard reload: Remove extension and re-add it

Testing Specific Features

Test PDF Detection

1. Ensure extension is loaded and service worker is running
2. Download any PDF file from the web
3. Check service worker console for "PDF detected:" log
4. Verify badge shows "1"
5. Open popup and verify PDF info is displayed

Test Credential Management

1. Open popup
2. Enter credentials
3. Check Chrome DevTools → Application → Storage → Extension Storage
4. Verify credentials are encrypted
5. Test credential expiry by manipulating storage

Test Alarm/Expiry Check

1. Open chrome://serviceworker-internals/
2. Check for alarm registration
3. Or use: chrome.alarms.getAll(console.log) in service worker console

Production Build & Testing

# Build for production
npm run build

# Build is in dist/ directory
# Test the production build by loading dist/ as unpacked extension

Running Unit Tests

# Run tests once
npm test

# Run tests in watch mode
npm run test:watch

# Type checking
npm run type-check

# Linting
npm run lint
npm run lint:fix

Useful Chrome URLs for Extension Development

• chrome://extensions/ - Manage extensions
• chrome://serviceworker-internals/ - Debug service workers
• chrome://inspect/#service-workers - Inspect active service workers
• chrome://downloads/ - View downloads (for testing PDF detection)
• chrome://version/ - Check Chrome version

Debugging Tips

1. Console.log is your friend: Add logs liberally in development
2. Breakpoints: Use debugger; statements or set breakpoints in DevTools
3. Storage inspection: Check Application → Storage → Extension Storage in DevTools
4. Network tab: Monitor API calls to Binect
5. Performance: Use Performance tab to check service worker lifecycle
6. Memory: Watch for memory leaks in long-running service workers

VS Code Integration (Optional)

Add to .vscode/launch.json for debugging:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "Debug Extension",
      "url": "chrome://extensions/",
      "webRoot": "${workspaceFolder}/dist"
    }
  ]
}

Quick Reference Commands

# Development
npm run dev              # Watch mode with auto-rebuild
npm run build           # Production build
npm test                # Run tests
npm run lint            # Check code quality
npm run type-check      # TypeScript validation

# Chrome URLs
chrome://extensions/              # Extension management
chrome://serviceworker-internals/ # Service worker debugging

Emergency Cleanup

If extension gets stuck or behaves oddly:

# 1. Stop service worker
# Go to chrome://serviceworker-internals/ → Stop

# 2. Clear extension storage
# DevTools → Application → Storage → Clear site data

# 3. Remove and reload extension
# chrome://extensions/ → Remove → Load unpacked again

# 4. Clean rebuild
rm -rf dist/
npm run build