Chrome插件自动化测试：单元测试、集成测试

前言

Chrome 插件（Extension）由 background service worker、content script、popup 等多部分组成，逻辑分散且依赖浏览器运行时，很多团队只靠"手动点一遍"来验证功能，结果一发布就出线上问题。本文以一款单平台视频下载 Chrome 插件（MuxDesk，作为案例）为背景，给出可落地的单元测试与集成测试方案，附完整可运行代码。

为什么插件测试特别难？第一，代码跑在浏览器沙箱里，chrome.* API 在 Node 环境下不存在；第二，content script 注入到网页上下文，和页面 DOM 强耦合；第三，Manifest V3 的 service worker 不持久，全局状态跨事件会丢失。这些特性决定了：不能把所有逻辑都堆在入口里，必须先把可测的纯逻辑抽出来，再对运行时行为做集成覆盖。

我见过一个真实教训：某插件把"解析视频地址"的逻辑写在 content script 顶层，一次源站改版后正则失效，用户点是"点了没反应"，但本地手动测试时因为缓存没更新反而正常，于是带病发了版，一天收到几十条差评。后来团队把解析规则全部抽成纯函数配单测，每次改完先跑测试，同类回归再没出现过。测试不是负担，是给频繁迭代上的保险。

在具体落地时，我倾向于用"测试金字塔"的思路：底层是大量便宜的单元测试，覆盖纯逻辑；中层是少量集成测试，覆盖组件拼装；顶层是极少的端到端测试，只验证关键路径。把精力放在底层，性价比最高。MuxDesk 的解析函数有上百条单测，而端到端只保留了"popup 能开、能触发下载"这一条，既省时又够用。

环境准备

Node.js ≥ 18
包管理器：npm
单元测试：jest + @types/chrome
集成测试：@puppeteer/browsers + puppeteer（驱动真实 Chrome 加载插件）
类型声明：在 tsconfig.json 或 jest.config 中引入 @types/chrome，让 chrome.* API 有补全

安装依赖：

bash 复制代码

# 在项目根目录执行
npm init -y
npm install -D jest @types/chrome ts-jest typescript
npm install -D puppeteer

jest.config.js 关键配置：

javascript 复制代码

/** @type {import('jest').Config} */
module.exports = {
  testEnvironment: 'node',      // 单元测试不依赖 DOM
  roots: ['<rootDir>/tests'],   // 测试文件目录
  transform: {
    '^.+\\.ts$': ['ts-jest', { tsconfig: { strict: true } }],
  },
};

实现步骤

动手前先记住一条原则：能不碰 chrome.* 就不碰。凡是涉及网络、存储、UI 的逻辑，尽量包一层接口，测试时用 mock 替代。下面这三段代码就是按这个原则拆出来的，utils.ts 完全不依赖浏览器 API，因此可以脱离插件直接跑单测。

1. 可被测试的核心逻辑（utils.ts）

把"解析视频地址""生成文件名"等纯逻辑抽成独立模块，不依赖 chrome.*，便于单测。

typescript 复制代码

// utils.ts
/** 根据页面 URL 与标题生成安全的本地文件名（去掉非法字符） */
export function buildSafeFileName(raw: string, ext = 'mp4'): string {
  // 去掉 Windows / Mac 文件名禁用的字符
  const cleaned = raw
    .replace(/[\\/:*?"<>|]/g, '_')
    .trim()
    .slice(0, 60);              // 控制长度，避免系统报错
  return `${cleaned || 'video'}.${ext}`;
}

/** 从一组候选地址里挑出清晰度最高的（按分辨率数值排序） */
export function pickBestSource(sources: { url: string; height: number }[]): string {
  if (sources.length === 0) throw new Error('no source');
  return [...sources].sort((a, b) => b.height - a.height)[0].url;
}

2. 单元测试（tests/utils.test.ts）

typescript 复制代码

import { buildSafeFileName, pickBestSource } from '../utils';

describe('buildSafeFileName', () => {
  it('去除非法字符', () => {
    expect(buildSafeFileName('a/b:c*?mp4')).toBe('a_b_c_mp4.mp4');
  });
  it('空字符串兜底', () => {
    expect(buildSafeFileName('   ')).toBe('video.mp4');
  });
});

describe('pickBestSource', () => {
  it('返回最高分辨率地址', () => {
    const src = [
      { url: 'a.mp4', height: 480 },
      { url: 'b.mp4', height: 1080 },
    ];
    expect(pickBestSource(src)).toBe('b.mp4');
  });
  it('无源时抛错', () => {
    expect(() => pickBestSource([])).toThrow('no source');
  });
});

运行：npx jest tests/utils.test.ts

3. 集成测试（tests/extension.e2e.test.ts）

用 Puppeteer 加载已打包的插件，验证"点击 popup 里的下载按钮能触发一次下载请求"。

typescript 复制代码

import puppeteer from 'puppeteer';

const EXT_PATH = './dist'; // 已 build 的插件目录（含 manifest.json）

describe('MuxDesk 插件集成测试', () => {
  let browser: any;
  beforeAll(async () => {
    browser = await puppeteer.launch({
      headless: true,
      args: [
        `--disable-extensions-except=${EXT_PATH}`,
        `--load-extension=${EXT_PATH}`,
      ],
    });
  });
  afterAll(async () => { await browser.close(); });

  it('popup 能正常打开并包含下载入口', async () => {
    const page = await browser.newPage();
    // 打开插件 popup 页面
    const targets = await browser.targets();
    const popup = targets.find(
      (t: any) => t.type() === 'page' && t.url().includes('popup')
    );
    const popupPage = popup ? await popup.page() : await browser.newPage();
    const html = await popupPage.content();
    expect(html).toContain('下载'); // 验证关键入口存在
  });
});

说明：集成测试依赖真实 Chrome 与已打包插件；CI 中建议用 @puppeteer/browsers 固定 Chrome 版本，避免环境漂移导致时好时坏。单测负责"逻辑对不对"，集成测试负责"拼起来能不能用"，两者分工不同，不能互相替代。

常见问题

chrome 未定义 ：单元测试里没有浏览器运行时。解法是用 jest.mock('webextension-polyfill') 或手写 stub，别让业务逻辑直接调 chrome.*。
content script 测不了：content script 跑在页面上下文，建议把解析逻辑抽成纯函数单测，再用集成测试覆盖注入行为。
Manifest V3 的 service worker 不持久 ：测试后台逻辑时，用 chrome.runtime 事件触发，不要假设全局变量跨事件存活。
集成测试偶发超时 ：真实浏览器启动慢，给 jest 加 testTimeout，并在 CI 用缓存加速 Chrome 下载。
popup 页面拿不到 ：Puppeteer 加载扩展后 popup 是延迟创建的，需在点击动作后再 browser.targets() 查找，而非启动即找。
host_permissions 缺失导致上报失败 ：测试埋点时，manifest 必须声明上报域名，否则 fetch 被静默拦截，测试永远等不到事件。

关于覆盖率，不必追求 100%。对插件来说，真正该覆盖的是"容易随源站变化而坏掉"的解析逻辑，以及"一出错用户就卡死"的入口流程。把覆盖率门槛设在 70% 左右、但关键模块要求 90%，比盲目拉满更务实。再配合 CI 在每次提交时自动跑测试和打包，问题能在合并前就暴露。

扩展阅读

Chrome 官方：Testing Extensions 文档
webextension-polyfill：让 chrome.* 返回 Promise，便于异步测试与 mock
Puppeteer 官方文档：Extension 加载参数与无头模式限制
jest 官方：Timer Mocks 与 Fake Timers，用于测试节流/防抖逻辑

总结

插件测试的核心是"分层"：纯逻辑用单元测试快速覆盖，跨组件行为用集成测试兜底。把下载地址解析、文件名生成等抽成无副作用函数，单测成本几乎为零；再配合 Puppeteer 加载真实插件，就能在发布前拦住大部分回归问题。对 MuxDesk 这款单平台视频下载插件来说，稳定的测试体系比多一个花哨功能更重要------毕竟用户不会因为一个炫技特性原谅"点开就崩"。把测试写进发版流程，是团队从"能跑"走向"稳跑"的分水岭。对于独立开发者，建议至少守住单测这条底线：它写起来最便宜，却能在源站一次次改版时替你挡掉大多数半夜告警。测试一旦成为肌肉记忆，迭代速度反而会更快，因为你不再害怕改动。这也是 MuxDesk 团队一直坚持的做法。

标签：Chrome插件开发, 自动化测试, 视频下载, MuxDesk, JavaScript