electron-vue 测试指南:基于 Karma + Mocha 与 Spectron 的单元测试和端到端测试实践
electron-vue 测试指南:基于 Karma + Mocha 与 Spectron 的单元测试和端到端测试实践
导读
本文围绕 electron-vue 脚手架内置的 Testing 支持,系统讲解 renderer 进程的单元测试(Karma + Mocha + Chai)与端到端测试(Spectron + Mocha + Chai)两套测试体系的运行方式、目录结构与配置原理,并介绍如何借助 Travis CI 与 AppVeyor 在 darwin、linux、win32 三平台自动化执行测试。读完本文,你将掌握 electron-vue 项目的测试命令、测试文件组织、关键配置文件的作用,以及源码级的测试运行机制,能够直接在自己的项目中编写和运行测试。
electron-vue 同时为 renderer 进程提供单元测试与端到端测试支持,其测试方案深受官方 vuejs-templates/webpack 样板工程的启发。在使用 vue-cli 脚手架生成项目时,交互式提问会询问是否引入测试支持——勾选后即会在生成的项目中注入 test/ 目录及对应的 npm scripts(见 template/package.json)。
测试体系总览与命令速查
electron-vue 将测试拆分为两个独立子系统,并在 package.json 的 scripts 中注册了统一入口(由脚手架模板 template/package.json 生成,{{#unit}}、{{#e2e}} 为 vue-cli 模板条件占位,按你的选择展开):
| 命令 | 用途 | 技术栈 |
|---|---|---|
npm run unit |
运行单元测试 | Karma 测试运行器 + Mocha 测试框架 |
npm run e2e |
运行端到端测试 | Spectron + Mocha 测试框架 |
npm test |
依次运行全部测试(单元 + 端到端) | 上述两者的组合 |
生成后的项目脚本形如:
"test": "npm run unit && npm run e2e",
"unit": "karma start test/unit/karma.conf.js",
"e2e": "npm run pack && mocha test/e2e"
注意 e2e 脚本在真正启动 Mocha 之前会先执行 npm run pack,为 Spectron 准备一份可供其消费的生产构建产物(详见下文“端到端测试”一节)。
单元测试:Karma + Mocha + Chai
electron-vue 的单元测试使用 Karma 作为测试运行器,Mocha 作为测试框架,并搭配 Chai 断言库。Mocha 与 Chai 分别通过 karma-mocha 和 karma-chai 两个适配器接入 Karma,因此诸如 expect 之类的断言 API 在测试文件中是全局可用的,无需在每个文件中显式 import。
运行单元测试
# 启动 Karma
npm run unit
该命令等价于 karma start test/unit/karma.conf.js,Karma 会读取配置文件、通过 webpack 预编译测试文件,并最终在 Electron 浏览器环境中执行全部 specs/ 下的测试。
单元测试目录结构
my-project
├─ test
│ ├─ unit
│ │ ├─ specs/
│ │ ├─ index.js
│ └─ └─ └─ karma.conf.js
官方文档建议:大多数情况下可以忽略 index.js 和 karma.conf.js,只需专注编写 specs/ 目录下的测试文件。不过理解这两个支撑文件能帮助你更好地排查配置问题。
specs/:真正编写测试的地方
测试用例全部写在 specs/ 目录下(文件以 .spec.js 结尾)。得益于 webpack 的参与,测试文件可以使用完整的 ES2015 语法以及项目已配置的各类 loader。仓库自带的示例 template/test/unit/specs/LandingPage.spec.js 展示了最典型的 Vue 组件挂载测试写法:
import Vue from 'vue'
import LandingPage from '@/components/LandingPage'
describe('LandingPage.vue', () => {
it('should render correct contents', () => {
const vm = new Vue({
el: document.createElement('div'),
render: h => h(LandingPage)
}).$mount()
expect(vm.$el.querySelector('.title').textContent).to.contain('Welcome to your new project!')
})
})
这个用例先创建一个挂载到虚拟 div 上的 Vue 实例渲染 LandingPage 组件,再断言组件 DOM 中 .title 节点的文本内容。这里直接使用了全局 expect 断言,验证了 “Chai API 全局可用” 的设计。
index.js:karma-webpack 的入口文件
index.js 是 karma-webpack 使用的入口文件,作用是以“一次性”的方式收集所有测试代码与源码。仓库实现 template/test/unit/index.js 使用 webpack 的 require.context 完成收集:
import Vue from 'vue'
Vue.config.devtools = false
Vue.config.productionTip = false
// 收集所有以 .spec 结尾的测试文件
const testsContext = require.context('./specs', true, /\.spec$/)
testsContext.keys().forEach(testsContext)
// 收集 src/renderer 下除 main.js 之外的所有源文件,用于覆盖率统计
const srcContext = require.context('../../src/renderer', true, /^\.\/(?!main(\.js)?$)/)
srcContext.keys().forEach(srcContext)
从源码可以看到两点细节:其一,入口会关闭 Vue 的 devtools 与 productionTip,避免测试输出噪声;其二,srcContext 会把 src/renderer 下除 main.js 外的所有源码一并引入,这正是覆盖率(coverage)报告的统计来源——如果你只想统计部分子集,可以按需修改这条 require.context 的正则。
karma.conf.js:Karma 的实际配置
karma.conf.js 中存放真正的 Karma 配置,默认装配了 spec 报告器与 coverage 覆盖率报告器。仓库的 template/test/unit/karma.conf.js 完整呈现了这一配置,关键点如下:
process.env.BABEL_ENV = 'test' // 使用正确的 babel preset 配置
let webpackConfig = merge(baseConfig, {
devtool: '#inline-source-map',
plugins: [
new webpack.DefinePlugin({
'process.env.NODE_ENV': '"testing"'
})
]
})
// 不把依赖当作 externals
delete webpackConfig.entry
delete webpackConfig.externals
delete webpackConfig.output.libraryTarget
配置主体在 config.set({...}) 中完成:
config.set({
browsers: ['visibleElectron'],
client: { useIframe: false },
coverageReporter: {
dir: './coverage',
reporters: [
{ type: 'lcov', subdir: '.' },
{ type: 'text-summary' }
]
},
customLaunchers: {
'visibleElectron': {
base: 'Electron',
flags: ['--show']
}
},
frameworks: ['mocha', 'chai'],
files: ['./index.js'],
preprocessors: {
'./index.js': ['webpack', 'sourcemap']
},
reporters: ['spec', 'coverage'],
singleRun: true,
webpack: webpackConfig,
webpackMiddleware: { noInfo: true }
})
需要留意的几个设计点:
- 测试运行在 Electron 环境中:通过
karma-electron提供base: 'Electron'的自定义 launcher,并传入--show标志显示测试窗口;useIframe: false让测试直接在 Electron 渲染进程中运行(而非 iframe)。 - webpack 配置复用生产渲染配置:配置基于
.electron-vue/webpack.renderer.config合并而来,先继承项目渲染进程的 webpack 配置,再删除entry、externals与output.libraryTarget,避免入口与外部化配置干扰测试打包;同时把vue-loader内部的 JS loader 替换为babel-loader(webpackConfig.module.rules.find(rule => rule.use.loader === 'vue-loader').use.options.loaders.js = 'babel-loader'),确保覆盖率统计(isparta/istanbul)能够介入。 - 覆盖率输出:
coverageReporter配置了lcov与text-summary两种报告,lcov报告输出到./coverage目录,可对接各类覆盖率展示服务。
官方还提示:进一步的自定义请参照 Karma 官方配置文档(karma-runner.github.io/1.0/config/configuration-file.html)进行。
Mock 依赖注入
electron-vue 默认安装并配置了 inject-loader,用于在单元测试中 mock 组件依赖。结合 Vue 组件文件使用时,请参考 vue-loader 官方文档中关于“使用 mock 进行测试”的章节(vue-loader 文档 testing-with-mocks)。inject-loader 的依赖声明位于 template/package.json 的 devDependencies({{#if unit}} 条件块内),只有在脚手架阶段选择了 unit testing 才会被安装。
端到端测试:Spectron + Mocha + Chai
端到端测试使用 Spectron 与 Mocha(搭配 Chai)完成。与单元测试一样,Mocha 与 Chai 的 API——包括 expect、should、assert——都被挂载到全局作用域,测试文件中可直接使用。
运行端到端测试
# 启动 Mocha
npm run e2e
重要前提:在运行端到端测试之前,npm run e2e 会先调用 npm run pack 生成一份生产构建产物,供 Spectron 在测试期间消费。从 template/package.json 可以看到 pack 的定义:
"pack": "npm run pack:main && npm run pack:renderer",
"pack:main": "cross-env NODE_ENV=production webpack --progress --colors --config .electron-vue/webpack.main.config.js",
"pack:renderer": "cross-env NODE_ENV=production webpack --progress --colors --config .electron-vue/webpack.renderer.config.js"
即先以生产模式分别打包主进程(main)与渲染进程(renderer)的 webpack 产物到 dist/,随后 mocha test/e2e 才会启动并驱动打包好的 Electron 应用。
端到端测试目录结构
my-project
├─ test
│ ├─ e2e
│ │ ├─ specs/
│ │ ├─ index.js
│ └─ └─ └─ utils.js
官方建议:大多数情况下可以忽略 index.js,只需专注编写 specs/ 下的测试。
specs/:编写端到端用例
测试用例位于 specs/ 目录。得益于 babel-register,这些文件同样可以使用完整的 ES2015 语法。仓库自带的示例 template/test/e2e/specs/Launch.spec.js 如下:
import utils from '../utils'
describe('Launch', function () {
beforeEach(utils.beforeEach)
afterEach(utils.afterEach)
it('shows the proper application title', function () {
return this.app.client.getTitle()
.then(title => {
expect(title).to.equal('{{ name }}')
})
})
})
这个用例验证应用窗口标题是否与项目名称一致,其中 {{ name }} 是脚手架模板占位符,生成项目时会被替换为实际项目名。注意用例函数使用了普通 function 声明而非箭头函数——这一点非常关键,见下文“使用 WebDriverIO”的说明。
index.js:Mocha 的主入口
index.js 是 Mocha 的主入口,负责收集 specs/ 下所有测试。仓库实现 template/test/e2e/index.js:
process.env.BABEL_ENV = 'test'
// 让被 require 的文件支持 ES6+
require('babel-register')({
ignore: /node_modules/
})
// 将 Chai API 挂载到全局
const { expect, should, assert } = require('chai')
global.expect = expect
global.should = should
global.assert = assert
// 收集 ./specs 下所有 JS 文件供 Mocha 使用
require('require-dir')('./specs')
这里通过 babel-register 开启 ES2015 支持,用 require-dir 一次性加载 specs/ 下全部文件,并通过 global 赋值把 expect、should、assert 暴露到全局——这正是端到端测试中可以直接使用断言 API 的机制来源。
utils.js:通用辅助函数
utils.js 存放整个 specs/ 都可能用到的通用函数,基础功能是提供负责 Electron 应用创建/销毁流程的 beforeEach 与 afterEach。仓库实现 template/test/e2e/utils.js:
import electron from 'electron'
import { Application } from 'spectron'
export default {
afterEach () {
this.timeout(10000)
if (this.app && this.app.isRunning()) {
return this.app.stop()
}
},
beforeEach () {
this.timeout(10000)
this.app = new Application({
path: electron,
args: ['dist/electron/main.js'],
startTimeout: 10000,
waitTimeout: 10000
})
return this.app.start()
}
}
可以看到 beforeEach 用 new Application({ path: electron, args: ['dist/electron/main.js'], ... }) 创建 Spectron 应用实例并调用 this.app.start() 启动;afterEach 则检查应用是否仍在运行并调用 this.app.stop() 关闭。args: ['dist/electron/main.js'] 与 npm run pack 产出的主进程入口(package.json 中 main 字段指向 ./dist/electron/main.js)一一对应,印证了“先打包、后测试”的运行链路。两个钩子都设置了 10 秒超时,避免启动缓慢导致测试挂起。
关于 Spectron 本身
Spectron 是 Electron 官方的测试框架,底层通过 ChromeDriver 与 WebDriverIO 来操纵 DOM 元素。它让测试代码能够像浏览器自动化测试一样控制 Electron 应用窗口。
使用 WebDriverIO
按照 Spectron 官方文档,WebDriverIO 的 API 可以通过 this.app.client 访问。由于 electron-vue 使用 Mocha,this 的上下文会在 afterEach、beforeEach 与 it 之间共享,因此在部分场景下不能使用 ES2015 箭头函数——箭头函数会覆盖 this 的绑定(参见 Mocha 关于箭头函数的说明)。这就是上面 Launch.spec.js 中测试函数使用普通 function () {...} 而非 () => {...} 的原因:只有这样才能在用例体内通过 this.app.client 访问 Spectron 客户端。
例如,通过 WebDriverIO 获取窗口标题并断言:
it('shows the proper application title', function () {
return this.app.client.getTitle()
.then(title => {
expect(title).to.equal('MyApp')
})
})
WebDriverIO 的完整 API(元素选择、交互、等待等)可以参考其官方 API 文档,均可通过 this.app.client 直接调用。
在 CI 上运行测试:Travis CI 与 AppVeyor
如果你在脚手架阶段选择 electron-builder 作为构建工具,那么可以轻松地在 Travis CI 与 AppVeyor 上针对 darwin、linux 和 win32 三个平台测试你的应用。仓库模板在 template/appveyor.yml(以及脚手架对应的 .travis.yml)中预置了被注释掉的测试段落,取消注释即可启用 CI 测试。
以 appveyor.yml 为例,仓库模板中的相关片段如下:
# Commented sections below can be used to run tests on the CI server
# https://simulatedgreg.gitbooks.io/electron-vue/content/en/testing.html#on-the-subject-of-ci-testing
build_script:
#- yarn test # ← 取消注释即可在 CI 上运行全部测试
- yarn build
同时,install 阶段会执行 yarn 安装依赖,cache 段缓存了 node_modules、npm/yarn 缓存以及 Electron 二进制(%USERPROFILE%\.electron),从而加快 CI 构建速度。针对 Travis CI,脚手架还会生成对应配置(Travis 负责构建 linux 与 darwin,AppVeyor 负责构建 win32)。这些文件只有在脚手架阶段同时选择了 testing 支持与 electron-builder 时才会注入对应的注释块。
关于在 CI 上自动化部署(将构建产物发布到 GitHub Release、Bintray 等,以及如何设置 GH_TOKEN 环境变量),请进一步阅读 docs/pt_BR/using-electron-builder.md 中的 Automated Deployments using CI 一节。
进一步阅读
本文对应的原始文档位于 docs/pt_BR/testing.md,与该主题强相关的仓库内文档与代码还包括:
- docs/pt_BR/unittesting.md:单元测试详细说明(Karma/Mocha/Chai 集成、
inject-loadermock 用法) - docs/pt_BR/end-to-end_testing.md:端到端测试详细说明(Spectron、WebDriverIO、
this上下文注意事项) - docs/pt_BR/using-electron-builder.md:含 Automated Deployments using CI 一节,说明 Travis/AppVeyor 的完整部署配置
- template/test/unit/karma.conf.js、template/test/unit/index.js、template/test/unit/specs/LandingPage.spec.js:单元测试实际配置与示例用例
- template/test/e2e/index.js、template/test/e2e/utils.js、template/test/e2e/specs/Launch.spec.js:端到端测试入口、辅助函数与示例用例
- template/package.json:
unit、e2e、test、pack等脚本及全部测试相关依赖的声明 - template/appveyor.yml:CI 测试段的注释配置示例
小结
electron-vue 的测试体系围绕“渲染进程”展开:单元测试借助 Karma 在 Electron 环境内通过 webpack 预编译并执行 specs/ 用例,同时基于 require.context 收集源码实现覆盖率统计;端到端测试则先由 npm run pack 产出生产构建,再由 Spectron 驱动真实应用、通过 this.app.client(WebDriverIO)操纵 DOM 并断言行为。两条链路均以“专注编写 specs/ 目录”为日常开发范式,配合 inject-loader 的依赖 mock 与 CI 上取消注释即可启用的测试配置,构成了从本地到持续集成的完整测试闭环。