poi 零配置 Karma 浏览器测试指南:@poi/plugin-karma 从接入到源码原理

原创2026-10-14 13:02:371,769 阅读
文章标签:构建工具前端

poi 零配置 Karma 浏览器测试指南:@poi/plugin-karma 从接入到源码原理

导读:本文以 poi 官方仓库中的 @poi/plugin-karma 文档与变更日志 为主体,结合该插件在仓库内的完整源码(入口实现、Karma 运行器)与 poi 核心(PoiCore)深入讲解。读完你将掌握:如何在 poi 项目中零配置接入 Karma + Jasmine 做自动化的无头浏览器单元测试,如何使用 poi test:unit 命令与 --coverage、--watch、--no-headless 等参数,并理解插件注入 CLI 命令、驱动 webpack 编译测试文件、生成覆盖率报告背后的完整调用链。

一、插件定位:为 poi 预配置好的浏览器测试环境

@poi/plugin-karma 是 poi 官方插件体系中负责自动化(无头)浏览器测试的一环,版本号与 poi 12.x 主版本线保持同步(仓库内当前版本为 13.0.4,见 plugins/karma/package.json)。

它做的事情可以概括为一句话(源自 README 引言):预先为你配置好 Karma 与 Jasmine,让你"不需要任何配置"就能跑浏览器测试。

具体而言,插件帮你完成了几层工作:

  • 集成了 Karma(测试运行器,负责在真实浏览器中启动测试页面);
  • 集成了 Jasmine(测试框架,提供 describe / it / expect 等断言 API);
  • 通过 karma-webpack 复用 poi 的 webpack 配置来编译测试文件,因此你的 Babel、TypeScript、Vue、CSS 等既有构建能力在测试中天然生效;
  • 通过 karma-chrome-launcher 提供 Chrome 启动器,默认使用 Chrome Headless(无头模式),适合本地与 CI 环境。

从 plugins/karma/package.json 的依赖清单可以看到这套技术栈的完整拼图:

依赖包 作用
karma(^5.0.3) 测试运行器核心
karma-jasmine Jasmine 测试框架适配
karma-chrome-launcher 启动 Chrome / Chrome Headless
karma-webpack 用 webpack 编译测试文件并喂给浏览器
karma-mocha-reporter 更友好的 mocha 风格测试输出
karma-coverage 覆盖率采集与报告
istanbul-instrumenter-loader 源码插桩,支撑覆盖率统计
fast-glob 批量展开测试文件匹配模式

二、安装与注册:三步接入项目

1. 安装插件

按照 README 安装章节:

yarn add @poi/plugin-karma --dev

插件本身只会作为构建/测试期工具被使用,因此务必安装到 devDependencies。

2. 在 poi.config.js 中注册

// poi.config.js
module.exports = {
  plugins: [
    {
      resolve: '@poi/plugin-karma'
    }
  ]
}

3. 插件的解析过程(源码佐证)

从 core/poi/lib/utils/plugins.js 可以看到,poi 在加载配置后会对 plugins 数组做 normalizePlugins 归一化:字符串形式的 resolve 会被尝试解析为实际模块路径(本地路径直接使用;@poi/xxx 会被规范化为 @poi/plugin-xxx 并优先尝试),解析失败会抛出 Cannot find plugin ... in your project 并提示"是否忘记安装"。随后 mergePlugins 会将配置文件里的插件与 --plugin 命令行参数指定的插件合并去重。

在 PoiCore 构造流程 中,插件的 cli 方法会在 CLI 初始化阶段被调用(extendCLI),apply 方法在配置合并与校验之后被调用——这正是 CHANGELOG 中 13.0.2 版本修复项"execute plugins after validating config"(execute plugins after validating config,变更日志)所确立的顺序:先校验配置,再执行插件,避免插件在拿到未校验配置时误判。

三、核心命令:poi test:unit

插件注册成功后,会向 poi CLI 注入一个新命令:

poi test:unit [...testFiles] [options]

该命令定义于 plugins/karma/lib/index.js:

exports.cli = api => {
  api.cli
    .command('test:unit [...testFiles]', 'Run unit tests with Karma')
    .usage('test:unit [...testFiles] [options]')
    .option('-w, --watch', 'Watch files')
    .option('--no-headless', 'Run with Chrome instead of Chrome Headless')
    .option('--coverage', 'Report code coverage')
    .action((testFiles, options) => { ... })
}

命令如何触发 poi 的 test 模式

命令名 test:unit 以 test 开头,这一点对 poi 核心有特殊意义。在 PoiCore 构造函数 中有如下判定:

if (this.args.args[0] && /^test(:|$)/.test(this.args.args[0])) {
  this.mode = 'test'
}

即凡是 test:xxx 或 test 开头的命令,poi 都会自动进入 test 模式(NODE_ENV=test)。test 模式下 poi 还会在配置校验阶段强制关闭编译缓存(见 validateConfig.js 的 // Always disable cache in test mode 注释),保证测试永远基于最新源码而非缓存产物。

在 npm scripts 中包装

为了让日常使用更顺手,README 建议在 package.json 中配置脚本(README npm scripts 示例):

{
  "name": "my-project",
  "scripts": {
    "test": "poi test:unit",
    "build": "poi --prod",
    "start": "poi --serve"
  },
  "devDependencies": {
    "poi": "^12.0.0"
  }
}

之后直接运行 npm test 即可。

注意(13.0.0 破坏性变更):在 13.0.0 版本中,插件简化了 CLI 用法(simplify CLI usage),并引入了唯一一次 BREAKING CHANGES——旧的 poi karma --test 写法被移除,统一改为 poi test:unit(见 CHANGELOG 13.0.0 条目)。如果你从旧版本升级,需要同步迁移命令写法。

四、测试文件匹配模式

默认情况下,插件使用如下 glob 模式收集测试文件(README Test File Patterns 章节):

**/*.{test,spec}.{js,ts}

即匹配项目内任意层级、文件名为 xxx.test.js、xxx.spec.js、xxx.test.ts、xxx.spec.ts 的文件;node_modules 目录会被自动排除。

自定义匹配模式

test:unit 命令接受可变参数 [...testFiles],因此你可以直接传入任意 minimatch 模式覆盖默认值。注意务必加引号,避免 shell 把 * 展开:

poi test:unit "**/*.spec.coffee"

从源码看,run-karma.js 会把传入模式与排除规则合并后交给 fast-glob 展开:

const files = await glob(
  [
    '!**/node_modules/**',
    `!${path.join(path.relative(process.cwd(), api.config.output.dir), '**')}`
  ].concat(testFiles),
  { cwd }
)

这里除了排除 node_modules,还额外排除了 poi 的输出目录(默认 dist),避免把上一次构建产物误当作测试文件。若没有传入任何测试文件参数,则回退到默认模式(index.js 中的 testFiles.length === 0 ? ['**/*.{test,spec}.{js,ts}'] : testFiles)。

仓库内示例

仓库自带一个最小示例测试文件 plugins/karma/example/index.test.js:

describe('main', () => {
  it('works', () => {
    expect(1).toBe(1)
  })
})

同时 package.json 中提供了 example 脚本(poi test:unit --plugin .),可在插件目录内直接本地验证插件行为。

五、命令行参数详解

除默认行为外,插件共提供三个命令行参数,其定义与实现如下(参数定义见 lib/index.js,消费逻辑见 lib/run-karma.js):

1. --coverage:覆盖率报告

poi test:unit --coverage

开启后做两件事:

  • 对源码插桩:通过 api.hook('createWebpackConfig', ...) 在 webpack 配置中追加 istanbul-instrumenter rule,用 istanbul-instrumenter-loader(开启 esModules: true)预处理所有 .js(x) 文件,并排除 node_modules 与 *.test.js(x) 自身(lib/index.js 第 11-27 行)。
  • 输出三类报告:在 ./coverage 目录下同时生成 text(终端文本)、html(coverage/report-html)与 lcov(coverage/report-lcov)三种格式(run-karma.js 第 49-56 行):
coverageReporter: {
  dir: 'coverage',
  reporters: [
    { type: 'text' },
    { type: 'html', subdir: 'report-html' },
    { type: 'lcov', subdir: 'report-lcov' }
  ]
}

同时 reporters 数组会在开启时追加 coverage reporter(['mocha', options.coverage && 'coverage'].filter(Boolean)),过滤掉 false 后得到最终报告列表。

2. --watch:监听模式

poi test:unit --watch

开启后 Karma 服务器保持运行并监听文件变化,改动测试或源码后自动重跑。该参数直接映射到 Karma 配置的 singleRun 字段(run-karma.js 第 79 行):

singleRun: !options.watch

即:默认(不传 --watch)singleRun: true,跑完一轮即退出,适合 CI;传入 --watch 后 singleRun: false,进入常驻监听。

3. --no-headless:切换有头 Chrome

默认使用 Chrome Headless;若需要肉眼观察浏览器中测试的运行情况(调试、录屏等场景),可关闭无头模式,改用普通 Chrome:

poi test:unit --no-headless

对应的自定义启动器定义在 run-karma.js 第 24-32 行:

customLaunchers: {
  PoiChrome: { base: 'Chrome' },
  PoiChromeHeadless: {
    base: 'ChromeHeadless',
    flags: ['--no-sandbox']
  }
}

注意无头启动器自带 --no-sandbox flag,这是许多容器/CI 环境下 Chrome 能正常运行的关键。

六、在 CI 上运行

README 明确指出(CI 章节):要在 CircleCI 等持续集成平台运行本插件测试,测试环境必须安装 Chrome。由于插件默认走 Chrome Headless,且自带 --no-sandbox,因此在绝大多数 Linux CI 镜像中可直接运行 npm test;若你的 CI 基础镜像未包含 Chrome,需在构建阶段预先安装(如 CircleCI 的 circleci/chrome 类镜像,或 CI 配置中的 apt/浏览器安装步骤)。仓库根目录的 circle.yml 正是该插件与 poi 主仓库在 CircleCI 上跑测试的实例佐证。

七、源码级原理:run-karma.js 的完整调用链

抛开黑盒视角,来看 plugins/karma/lib/run-karma.js 如何把 poi 与 Karma 缝合在一起。整个模块是一个 async 函数,流程如下:

1. 构建 webpack 配置

const webpackConfig = api.createWebpackChain()

api.createWebpackChain() 是 poi 核心对外暴露的 webpack 配置工厂(实现见 core/poi/lib/index.js#L404-L450):它会依次执行内置插件注册的 createWebpackChain hooks(Babel、CSS、图片、HTML 等所有加载器配置均在此阶段注入,相关 hook 注册见 config-babel.js 等内置插件),随后合并用户配置中的 chainWebpack 自定义函数。

有趣的是,测试场景下应用自身的入口(entry)会被清空,因为测试入口由 karma-webpack 另行接管:

webpack: webpackConfig.entryPoints
  .clear()
  .end()
  .toConfig()

(run-karma.js 第 58-61 行)——即保留 poi 的加载器链,但丢弃应用入口,避免测试时捆绑应用入口文件。

2. 组装 Karma 配置

const config = {
  basePath: cwd,
  browsers: [options.headless ? 'PoiChromeHeadless' : 'PoiChrome'],
  customLaunchers: { ... },
  files: files.map(pattern => ({ pattern, watched: false })),
  preprocessors: files.reduce((res, pattern) => {
    res[pattern] = ['webpack']
    return res
  }, {}),
  frameworks: ['jasmine'],
  reporters: ['mocha', options.coverage && 'coverage'].filter(Boolean),
  coverageReporter: { ... },
  webpack: ...,
  webpackMiddleware: {
    logLevel: 'error',
    stats: 'errors-only',
    noInfo: true
  },
  colors: true,
  client: {
    captureConsole: true,
    jasmine: { random: false }
  },
  singleRun: !options.watch
}

几个值得注意的细节:

  • preprocessors:每个测试文件都挂上 webpack 预处理器,即由 karma-webpack 完成编译后再交给浏览器执行;
  • files 的 watched: false:文件监听交给 Karma 自身的 watch 逻辑(与 --watch 联动),避免 karma-webpack 与 webpack 的 watch 双轨冲突;
  • client.jasmine.random: false:禁用 Jasmine 默认的随机执行顺序,保证用例按书写顺序稳定执行,便于排查依赖顺序的用例;
  • webpackMiddleware 静默化:中间件只输出错误与统计摘要(stats: 'errors-only'),保持测试输出干净。

3. 启动服务器与错误处理

const server = createServer(config, api.PoiError)
server.start()
await server.completion

createServer 封装了 Karma Server 实例,并基于 Promise 暴露 completion(run-karma.js 第 89-111 行):Karma 退出码为 0 时正常 resolve;非零退出码则构造 PoiError(定义见 core/poi/lib/utils/PoiError.js,带 poi: true 标记与 dismiss 控制)并以 Karma has exited with code ${code} 拒绝,最终 await server.completion 把这一 Promise 结果透传给 poi test:unit 进程的退出状态——这就是为什么测试失败时 CI 任务会正确失败。

八、版本演进解读:从 CHANGELOG 看插件成熟轨迹

CHANGELOG.md 完整记录了 @poi/plugin-karma 从 12.0.2 到 13.0.4 的演进,可归纳为几条主线:

版本 日期 关键变更
13.0.4 2020-04-30 版本对齐(version bump only),无功能变更
13.0.3 2019-07-27 版本对齐,无功能变更
13.0.2 2019-01-22 Bug Fix:改为在配置校验之后再执行插件(closes #530)
13.0.1 2019-01-09 Bug Fix:支持 Yarn PnP(Plug'n'Play)
13.0.0 2019-01-09 Feature:简化 CLI 用法;BREAKING:poi karma --test → poi test:unit
12.0.3 2018-12-22 Bug Fix:修复 Karma 中被排除文件的处理(excluded files in karma)
12.0.2 2018-12-22 Feature:更新插件以匹配旧版行为(update karma plugin to match old behavior)

其中两条值得展开:

  • 13.0.1 的 Yarn PnP 支持:对应 poi 核心内置的 builtin:yarn-pnp 插件(config-yarn-pnp.js)——当 package.json 的 installConfig.pnp 开启时,会自动注入 @poi/pnp-webpack-plugin 到 resolve 与 resolveLoader,保证 PnP 环境下模块能被正确解析,Karma 测试自然不会因模块解析失败而崩溃。
  • 12.0.3 的 excluded files 修复:与 run-karma.js 中同时出现的 !**/node_modules/** 与输出目录排除规则直接相关——正是这一修复确立了"测试文件收集必须排除 node_modules 与构建产物"的语义。

九、适用范围与注意事项

  • 依赖 Chrome:无论本地还是 CI,测试都依赖 Chrome 可执行文件;无头模式通常无需额外 X 服务,但有头模式(--no-headless)在无图形环境的 CI 上不可用。
  • 仅适合浏览器侧测试:本插件面向浏览器自动化测试场景(Karma + Jasmine + Chrome),Node 环境的单元测试不在其职责范围。
  • 与 poi 版本配套:插件版本与 poi 12.x 主版本线同步(当前 13.0.4),接入时建议保持 poi 与插件同主版本,且按 13.0.0 起的新命令 poi test:unit 使用。

总体而言,@poi/plugin-karma 是 poi"零配置"哲学在测试域的延伸:安装、注册、写测试文件、npm test,四步即可获得一套在真实浏览器中运行、带 webpack 全量编译能力、可输出覆盖率报告的单元测试链路。

登录后查看全文
poi