testing-tool/AGENTS.md

AGENTS.md

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

项目概述

这是一个基于 WXT 框架的浏览器扩展项目，提供测试工具功能，包括时间戳转换等。

核心命令

开发相关

• npm run dev - 启动 Chrome 浏览器的开发模式
• npm run dev:firefox - 启动 Firefox 浏览器的开发模式
• npm run build - 构建 Chrome 浏览器的生产版本
• npm run build:firefox - 构建 Firefox 浏览器的生产版本
• npm run zip - 打包 Chrome 扩展
• npm run zip:firefox - 打包 Firefox 扩展
• npm run compile - TypeScript 类型检查（不生成文件）
• npm run lint - 运行 ESLint 检查

测试相关

• npm run test - 运行所有测试（单次执行）
• npm run test:watch - 运行测试并监听文件变化
• npm run test:coverage - 运行测试并生成覆盖率报告

运行单个测试文件：

npx vitest run components/__tests__/CopyButton.test.tsx

测试技术栈：

• Vitest - 测试框架
• @testing-library/react - React 组件测试
• @testing-library/user-event v13 - 用户交互模拟（注意：v13 不支持 setup()，使用 fireEvent）
• jsdom - 浏览器环境模拟

依赖与准备

• npm install - 安装依赖
• postinstall 会自动运行 wxt prepare 准备开发环境
• prepare 钩子会初始化 Husky Git 钩子

项目架构

技术栈

• 框架: WXT (Web Extension Toolkit) - 浏览器扩展开发框架
• 前端: React 19 + TypeScript
• UI 库: Material UI (MUI)
• 状态管理: React Hooks
• 路由: React Router DOM

目录结构

├── components/           # 可复用 UI 组件
│   ├── CopyButton.tsx           # 复制按钮组件
│   ├── DatetimeToTimestamp.tsx   # 日期转时间戳组件
│   ├── Navbar.tsx                # 导航栏组件
│   ├── RoutePersistence.tsx      # 路由持久化组件
│   ├── TimestampExecution.tsx    # 时间戳执行组件
│   └── TimestampToDatetime.tsx   # 时间戳转日期组件
├── entrypoints/          # 浏览器扩展入口点
│   ├── background.ts     # 后台脚本（主进程）
│   ├── content.ts        # 内容脚本（注入到页面）
│   └── popup/            # 扩展弹窗界面
│       ├── App.tsx       # 弹窗主应用
│       ├── main.tsx      # 弹窗入口
│       └── pages/        # 弹窗页面
│           ├── TestPage.tsx      # 测试页面
│           └── TimestampPage.tsx # 时间戳工具页面
├── utils/                # 工具函数
│   ├── chromeStorage.ts  # Chrome 存储工具
│   ├── dayjs.ts          # 日期处理工具
│   └── messages.tsx      # 消息通信工具
├── types/                # 类型定义
│   └── storage.d.ts      # 存储相关类型

核心功能实现

1. 时间戳转换工具

• 位置: components/ 目录下的时间戳相关组件
• 依赖: dayjs 库进行日期处理
• 功能: 支持日期与时间戳的双向转换，支持多种格式

2. 通信系统

• 位置: utils/messages.tsx
• 机制: 使用 @webext-core/messaging 库实现
• 通信通道: 后台脚本 ↔ 内容脚本 ↔ 弹窗

3. 数据存储

• Chrome Storage API: utils/chromeStorage.ts (用于配置等小数据)

关键配置文件

wxt.config.ts

• 配置 WXT 框架参数
• 启用 React 模块
• 配置浏览器扩展权限
• Vite 构建配置（使用 Terser 压缩，强制 ASCII 编码）

manifest 权限

permissions: [
  'storage',           // 存储权限
  'unlimitedStorage',  // 无限制存储
  'clipboardWrite',    // 剪贴板写入
  'activeTab',         // 当前标签页
  'scripting',         // 脚本注入
  'tabs',              // 标签页管理
  'debugger',          // 调试器
],
host_permissions: ['<all_urls>']  // 访问所有网站

开发注意事项

扩展入口点

• 后台脚本: entrypoints/background.ts - 处理扩展生命周期和后台任务
• 内容脚本: entrypoints/content.ts - 注入到网页中，处理 DOM 交互
• 弹窗: entrypoints/popup/main.tsx - 用户点击扩展图标时显示

浏览器兼容性

• 支持 Chrome 和 Firefox 浏览器
• 使用 WXT 框架抽象浏览器差异

代码质量

• 使用 ESLint 进行代码检查
• Husky 用于 Git 钩子管理
• Lint-staged 确保暂存文件符合规范