Chrome Auto Refresh

Version 0.3.2 — Chrome extension (Manifest V3) that lets you schedule automatic tab refreshes with per-tab control, real-time countdown badges, and robust persistence across tab suspension and service worker restarts.

Features

• Real-Time Badge Countdown: Extension icon displays remaining seconds (e.g., "45s", "2m") with automatic updates every second, capping at "99+" for large values.
• Tab Suspension & Persistence: Timers continue working even when Chrome discards inactive tabs to save memory. Alarms fire reliably, and badge updates survive service worker restarts.
• Per-Tab Control: Independent refresh intervals (5–1800 seconds) for each tab with start, stop, and clear operations.
• Live Interval Adjustment: Change an active timer by entering a new interval and pressing Start—no manual stop required.
• Paused Timer Recovery: Manual navigation pauses timers and preserves remaining delay. Timers resume automatically when you return to the same origin, even after browser restarts.
• Privacy-Conscious: Only stores tabId, intervalMs, timestamps, and remaining delay metadata—no URLs, titles, or page content.
• Manual Reload Resilience: Extension-triggered reloads are distinguished from user refreshes, so auto-refresh resumes automatically after manual navigation on the same origin.
• Sensible Defaults: Popup initializes with a 45-second interval that users can adjust at any time.
• Comprehensive Testing: 65 passing unit tests covering badge management, tab suspension, input validation, and error handling.

Project Structure

• manifest.json — Extension manifest (MV3) with background service worker and popup entry point.
• popup.html / popup.css / popup.js — Popup UI, styling, and UI logic for user interactions.
• service_worker.js — Timer scheduling, tab lifecycle handling, persistence, and messaging.
• DESIGN.md — High-level architecture, requirements, and implementation guidance.

Usage

1. Load the project as an unpacked extension via chrome://extensions.
2. Pin the extension (optional) and open the popup on any tab.
3. Enter an interval (seconds) and click Start to begin auto-refreshing the current tab.
4. Use Stop to cancel the timer or Clear Stored Timers to wipe all persisted jobs.

Interval Validation

• Minimum interval: 5 seconds (MIN_INTERVAL_MS in service_worker.js).
• Maximum interval: 30 minutes (1800 seconds) (MAX_INTERVAL_MS).
• Validation occurs in both the popup and the service worker to avoid invalid schedules.

Privacy Notes

• Stored data (activeJobs) contains only tabId, intervalMs, and optional lastRefresh timestamps.
• No URLs, titles, or page contents are captured.
• Use the Clear Stored Timers button or Chrome extension settings to remove stored metadata.

Manual Test Checklist

• Start/Stop: Start a timer on a tab and verify auto-refresh works; stop it and confirm reloads cease.
• Multiple Tabs: Run timers on multiple tabs and ensure they operate independently.
• Validation: Attempt intervals below 5 seconds or above 1800 seconds; verify error messages and rejection.
• Tab Lifecycle: Close or navigate away from a tab with an active timer; ensure the timer stops and storage clears.
• Persistence: Disable/enable the extension (or restart Chrome); confirm timers rehydrate for existing tabs, including paused ones that resume using their prior remaining delay.
• Clear Stored Timers: Use the popup button and confirm all timers stop and storage empties.
• Manual Reload Resilience: With auto-refresh active, press the browser refresh button. Verify popup shows a temporary pause state and the timer resumes once the page finishes loading (on same-origin navigation).
• Tab Suspension: Start a timer, minimize Chrome for 5+ minutes, restore and verify badge continues updating and timer fires on schedule.
• Tab Discard: Start a timer, use Chrome Task Manager (Shift+Esc) to manually discard the tab, verify timer continues and tab reactivates on next refresh.
• Badge Persistence: Start timer, close popup, verify badge shows countdown on browser toolbar icon. Wait for service worker to potentially restart (30+ seconds idle), verify badge continues updating.

Development

• Install dependencies: npm install
• Run unit tests: npm test
• Run E2E tests: npm run test:e2e (basic flows) or npm run test:e2e:suspension (tab suspension scenarios) or npm run test:e2e:all (all E2E tests)
• Tests rely on Node execution with mocks where necessary and cover core utility functions in service_worker.js.
• Recent additions include coverage for paused-timer persistence across pauses, resumes, storage restoration (single and multiple jobs), expired remaining delays, stopRefresh() cleanup (verifying timers and storage are purged), clearAllRefreshJobs() bulk removal, and handleMessage() dispatch paths for START, STOP, GET_STATUS, and CLEAR_ALL.
• Badge management tests: Comprehensive unit tests for updateBadgeForTab() and updateAllBadges() covering countdown display, 99+ cap, paused state clearing, closed tab handling, and integration with start/stop flows.
• Tab suspension tests: Unit tests verify timer persistence when tabs are discarded, service worker restart with remaining time preservation, multiple tabs with independent timers, and automatic cleanup on failed reloads.
• Popup-level tests ensure interval validation, message sequencing, status rendering, and the live countdown/badge behaviour under active and paused scenarios (__tests__/popup.test.js).
• Smoke-style integration tests simulate full flows: start/pause/resume with alarms, storage rehydration followed by stop, cross-origin navigation clearing timers, pruning invalid stored entries, and verifying the countdown badge (popup and toolbar) during multi-tab interactions (npm run test:e2e).
• E2E tab suspension tests (npm run test:e2e:suspension): Validates timer persistence in storage, badge countdown display, timer survival after tab discard, multiple tabs with independent timers, independent badge updates, storage cleanup on tab close, and remaining timer activity verification.

Future Enhancements

See DESIGN.md §14 for roadmap items like countdown displays, per-site scheduling, and global controls.

Live Remaining-Time Display

• The popup header shows a countdown badge next to the title whenever a timer is active, updating every second to reflect the remaining delay until the next reload.
• Countdown state derives from the service worker remainingMs / nextRunAt metadata and persists across reloads. Paused timers freeze the badge with a "Paused" label, and the display hides when timers stop or data is cleared.
• Multi-tab switching and manual reload flows are covered in tests so the countdown resumes accurately after service worker restores state, and the browser action badge mirrors those transitions.

Tab Suspension & Background Behavior

Chrome aggressively manages memory by suspending or discarding inactive tabs. This extension is designed to handle these scenarios robustly:

How It Works

• Persistent Timers: All timer state is stored in chrome.storage.local, ensuring timers survive tab suspension, service worker restarts, and even browser restarts.
• Alarm Continuity: The extension uses Chrome's Alarms API, which continues firing even when tabs are suspended or the service worker is inactive.
• Automatic Reactivation: When an alarm fires for a suspended/discarded tab, chrome.tabs.reload() automatically reactivates the tab and loads its content.
• Badge Countdown: The service worker maintains a 1-second interval that updates badges for all active timers, keeping the countdown accurate even across service worker restarts.

What Happens When...

• Tab is in background: Timer continues normally, badge updates every second, alarm fires on schedule.
• Tab is suspended by Chrome: Timer metadata persists in storage, alarm continues firing, badge shows countdown, tab reloads when alarm triggers.
• Tab is discarded (memory freed): Same as suspended—timer persists, alarm fires, tab reactivates on next refresh.
• Service worker restarts: On startup, extension reads storage, validates tabs still exist, reschedules alarms with preserved remaining time, resumes badge updates.
• Tab is closed: Timer and storage entry are automatically cleaned up via chrome.tabs.onRemoved listener.
• Reload fails (e.g., tab closed during suspension): Alarm handler detects error, automatically removes timer and storage entry.

Privacy & Storage

• Minimal data: Only tabId, intervalMs, lastRefresh timestamp, and remainingMs (when paused) are stored.
• No URLs or content: The extension never stores page URLs, titles, or any page content.
• Local only: All data stays on your device via chrome.storage.local (not synced to Google servers).
• Easy cleanup: Use "Clear Stored Timers" button in popup or Chrome's extension settings to remove all data.

Testing

• Unit tests: 56+ tests covering badge management, tab suspension, service worker restarts, and storage persistence.
• E2E tests: Automated browser tests verify multi-tab scenarios, tab discard handling, and badge persistence.
• Manual verification: See "Manual Test Checklist" above for tab suspension and badge persistence tests.