poi 零配置 Karma 浏览器测试指南:@poi/plugin-karma 从接入到源码原理
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-instrumenterrule,用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 全量编译能力、可输出覆盖率报告的单元测试链路。