testing-tool/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Quick Start

A browser extension built with the WXT framework, providing timestamp conversion and storage cleaning tools.

Essential Commands

Command	Purpose
npm install	Install dependencies (runs wxt prepare post-install)
npm run dev	Start development mode for Chrome
npm run dev:firefox	Start development mode for Firefox
npm run build	Build production version for Chrome
npm run build:firefox	Build production version for Firefox
npm run zip	Package Chrome extension
npm run zip:firefox	Package Firefox extension
npm run compile	TypeScript type checking (no file generation)
npm run lint	Run ESLint with zero warnings allowed

Setup

• Dependencies install automatically runs wxt prepare via postinstall hook
• Husky Git hooks are initialized via prepare script

Architecture Overview

Tech Stack

• Framework: WXT (Web Extension Toolkit)
• Frontend: React 19 + TypeScript
• UI Library: Material UI (MUI)
• Date Handling: dayjs (with UTC and timezone plugins)
• Communication: @webext-core/messaging
• Storage: Chrome Storage API with type-safe wrapper

Directory Structure

entrypoints/          # Browser extension entry points
├── background.ts     # Background script (injects content scripts)
├── content.ts        # Content script (injected into pages)
├── popup/            # Extension popup interface
│   ├── App.tsx       # Popup main application (handles routing)
│   ├── main.tsx      # Popup entry point
│   ├── index.html    # Popup HTML
│   └── pages/        # Popup pages
│       ├── TimestampPage.tsx      # Timestamp conversion
│       └── StorageCleanerPage.tsx # Storage cleaning
└── options/          # Options page (static HTML)
utils/                # Utility functions
types/                # TypeScript type definitions
public/               # Static assets

Extension Entry Points

• Background Script: Listens for install/update events, injects content scripts into valid tabs
• Content Script: Matches all URLs (<all_urls>), runs at document start (currently placeholder)
• Popup: Main interface with tab-based navigation between timestamp conversion and storage cleaning
• Options Page: Static HTML page, can be extended as settings interface

Core Features

Timestamp Conversion Tool (entrypoints/popup/pages/TimestampPage.tsx)

• Real-time current timestamp display (milliseconds/seconds toggle)
• Timestamp ↔ date/time conversion
• Support for multiple timezones (Asia/Shanghai, America/New_York, Europe/London)
• One-click copy functionality
• Input validation and error handling

Storage Cleaning Tool (entrypoints/popup/pages/StorageCleanerPage.tsx)

• Automatically reads current domain
• Cleans multiple storage types: localStorage, sessionStorage, IndexedDB, Cookies, Cache Storage, Service Workers
• User-selectable storage types (all selected by default)
• Confirmation dialog to prevent accidental cleaning
• Cleaning result statistics display
• Auto-refresh page after cleaning option
• User preferences persistence

Data Storage

Uses Chrome Storage API with type-safe wrapper (utils/chromeStorage.ts):

• Storage Schema (types/storage.d.ts): Interface-based type definitions
• Current storage keys:
  • app/currentRoute: Current active page route (default: 'timestamp')
  • app/visiblePages: List of visible pages (default: ['timestamp', 'storageCleaner'])
  • app/lastRoute: Last accessed route (legacy)
  • app/theme: Theme settings
  • storageCleaner/preferences: Storage cleaner preferences (autoRefresh, selectedTypes)

Development Workflow

Browser Compatibility

• Supports Chrome and Firefox browsers
• Uses WXT framework to abstract browser differences

Code Quality

• ESLint: Zero warnings enforced (npm run lint)
• Husky: Git hook management
• lint-staged: Ensures staged files comply (ESLint + TypeScript + Prettier)
• Prettier: Code formatting (100 char line width, 2 space indent, single quotes, trailing comma)

TypeScript Configuration

• Strict mode enabled (strict: true)
• noImplicitAny set to false (allows implicit any)
• Unused variables/parameters cause errors (noUnusedLocals, noUnusedParameters)
• Module resolution mode: Bundler
• Path alias: @/* maps to project root
• Excludes test files from type checking

Path Aliases

• Use @/ prefix for project-relative imports (e.g., @/utils/chromeStorage)
• Configured in tsconfig.json paths

Configuration & Implementation

wxt.config.ts

• Enables React module (@wxt-dev/module-react)
• Configures manifest permissions and host_permissions
• Uses Terser compression (forces ASCII encoding)
• Configures icons and options page

Manifest Permissions

permissions: [
  'storage',           // Chrome Storage
  'unlimitedStorage',  // Unlimited storage
  'clipboardWrite',    // Clipboard write (copy functionality)
  'activeTab',         // Current tab access
  'scripting',         // Script injection
  'tabs',              // Tab management
  'debugger',          // Debugger permissions
  'cookies',           // Cookies access (added for storage cleaning)
],
host_permissions: ['<all_urls>']  // Access all websites

Storage Cleaning Implementation Details

• Cookies: Uses chrome.cookies API directly in extension context
• Other storage types: Uses chrome.scripting.executeScript to inject cleaning scripts into page context
• Restricted page filtering: chrome://, about://, edge://, view-source://, file://, data://
• IndexedDB: Uses indexedDB.databases() to get database list, handles onblocked events
• Service Workers: Unregisters to prevent re-caching
• Cache Storage: Uses caches API to clear all caches

Messaging System

• Uses @webext-core/messaging library for type-safe extension communication
• Defined in utils/messages.tsx
• Current ProtocolMap is empty (reserved for future use)

CI/CD & Project Context

GitHub Actions Workflow (.github/workflows/node.js.yml)

• Triggers on push to main branch or pull requests
• Uses Node.js 20.x and 22.x for multi-version testing
• Runs ESLint, TypeScript compilation, and build steps
• Test commands are currently commented (project has no tests)

Project History

Recent refactoring streamlined the project:

• Removed recording and playback functionality
• Removed test pages
• Streamlined to single-page timestamp tool
• Renamed storage utility class to storageUtil
• Added storage cleaning functionality with persistent preferences
• Added route persistence for popup navigation