electron-vue 测试体系完全指南:Karma + Mocha 单元测试与 Spectron 端到端测试实战

原创2026-09-21 18:03:211,931 阅读
文章标签:前端桌面应用

electron-vue 测试体系完全指南:Karma + Mocha 单元测试与 Spectron 端到端测试实战

导读

本篇指南以 electron-vue 官方文档《测试》为核心,系统讲解脚手架内置的两套测试体系:基于 Karma + Mocha 的 renderer 进程单元测试,以及基于 Spectron + Mocha 的端到端测试。读完本文,你将掌握从 npm run unit、npm run e2e 到 npm test 的完整命令链,理解 test/unit 与 test/e2e 目录结构中每个文件的职责,并能结合仓库源码读懂 Karma 配置、Webpack 测试打包、Chai 全局断言与 CI 集成的底层原理,最终在真实项目中独立编写与接入测试。

electron-vue 为什么内置测试体系

electron-vue 是一套基于 vue-cli 脚手架的 Electron + Vue.js 快速启动样板工程,其测试能力深受官方样板 vuejs-templates/webpack 的启发。在 template/package.json 的模板中可以看到,测试相关依赖全部通过 {{#if unit}}、{{#if e2e}}、{{#testing unit e2e}} 等条件编译块按需注入,也就是说在 vue-cli 交互式脚手架阶段,你可以自行选择是否包含测试:

  • 选择单元测试(unit)时,会注入 karma、karma-mocha、karma-chai、karma-webpack、karma-coverage、karma-electron、inject-loader 等依赖(见 template/package.json);
  • 选择端到端测试(e2e)时,会注入 spectron、require-dir(见 template/package.json);
  • 只要选中了任一测试,就会注入 mocha、chai、babel-plugin-istanbul 作为共享测试框架(见 template/package.json)。

脚手架生成的 package.json 中,测试命令与构建命令被串联为完整的脚本链(见 template/package.json):

"e2e": "npm run pack && mocha test/e2e",
"test": "npm run unit && npm run e2e",
"unit": "karma start test/unit/karma.conf.js",
"pack": "npm run pack:main && npm run pack:renderer"

这套脚本链揭示了 electron-vue 的测试设计哲学:单元测试直接针对源码运行,端到端测试则必须先打包出产品构建,再让 Spectron 启动真实的应用进行黑盒验证。

单元测试:Karma + Mocha 驱动 renderer 进程

运行方式

单元测试的入口是一条命令:

npm run unit

底层执行的是 karma start test/unit/karma.conf.js(见 template/package.json),即启动 Karma 并以项目内的 karma 配置文件运行。Karma 是测试运行器,负责启动浏览器/宿主环境、调度用例执行与收集结果;Mocha 是测试框架,负责组织 describe / it 结构与断言;Chai 提供断言 API。

技术选型与集成原理

electron-vue 单元测试的核心组合是:

  • Karma:测试运行器,负责管理测试环境与进程;
  • Mocha + Chai:测试框架与断言库,通过 karma-mocha 与 karma-chai 两个适配器接入 Karma;
  • karma-webpack + karma-electron:前者负责用 Webpack 打包测试代码,后者让 Karma 直接运行在 Electron 渲染进程环境里(而非浏览器),这正是"renderer 进程单元测试"的由来。

由于 karma-chai 的接入,Chai 的所有 API(如 expect、should、assert)都可以在测试文件中全局直接使用,无需显式 import。这在测试代码中有直观体现——template/test/unit/specs/LandingPage.spec.js 中直接使用了 expect:

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!')
  })
})

这段模板测试展示了 Vue 组件单元测试的标准姿势:通过 new Vue(...) 手动实例化组件并 $mount() 到内存中的 div,再对渲染出的 DOM 文本做断言。

文件结构

脚手架生成的 test/unit 目录结构如下:

my-project
├─ test
│  ├─ unit
│  │  ├─ specs/
│  │  ├─ index.js
│  │  └─ karma.conf.js

文档特别强调:在大多数情况下,可以忽略 index.js 和 karma.conf.js,只专注于编写 specs/ 目录下的测试用例。三个文件的职责分工为:

specs/

实际编写测试代码的地方。由于 karma-webpack 会将测试文件交由 Webpack 打包处理,你可以完全依照 ES2015 语法以及 Webpack 支持的加载器(loader)来编写,包括使用 @/ 等别名引入组件(见 template/test/unit/specs/LandingPage.spec.js)。

index.js

karma-webpack 使用的入口文件,其目的是一次性收集加载所有的测试文件和源码(见 template/test/unit/index.js):

import Vue from 'vue'
Vue.config.devtools = false
Vue.config.productionTip = false

// require all test files (files that ends with .spec.js)
const testsContext = require.context('./specs', true, /\.spec$/)
testsContext.keys().forEach(testsContext)

// require all src files except main.js for coverage.
// you can also change this to match only the subset of files that
// you want coverage for.
const srcContext = require.context('../../src/renderer', true, /^\.\/(?!main(\.js)?$)/)
srcContext.keys().forEach(srcContext)

这里使用了 Webpack 的 require.context 能力:第一个上下文把 ./specs 下所有以 .spec 结尾的文件递归加载进来作为测试用例;第二个上下文把 src/renderer 下除 main.js 外的所有源码加载进来——这正是覆盖率统计的数据来源。注释还提示你可以调整正则,只对关心的文件子集收集覆盖率。

karma.conf.js

Karma 的实际配置文件(见 template/test/unit/karma.conf.js),与模板源码结合可拆解为以下几层:

Webpack 配置合并。Karma 配置基于 .electron-vue/webpack.renderer.config 合并出测试专用配置:

const baseConfig = require('../../.electron-vue/webpack.renderer.config')
const projectRoot = path.resolve(__dirname, '../../src/renderer')

// Set BABEL_ENV to use proper preset config
process.env.BABEL_ENV = 'test'

let webpackConfig = merge(baseConfig, {
  devtool: '#inline-source-map',
  plugins: [
    new webpack.DefinePlugin({
      'process.env.NODE_ENV': '"testing"'
    })
  ]
})

// don't treat dependencies as externals
delete webpackConfig.entry
delete webpackConfig.externals
delete webpackConfig.output.libraryTarget

// apply vue option to apply isparta-loader on js
webpackConfig.module.rules
  .find(rule => rule.use.loader === 'vue-loader').use.options.loaders.js = 'babel-loader'

关键点在于:delete webpackConfig.entry 和 delete webpackConfig.externals 移除了生产构建的入口与外部依赖声明,使 Webpack 能够从 Karma 的入口文件出发完整打包测试代码及其依赖;BABEL_ENV=test 让 Babel 使用测试环境预设;NODE_ENV 被定义为 'testing',与生产环境的 'production'、开发环境的 'development' 相区分,便于代码在测试分支下做针对性处理。

Karma 运行时配置。核心段落在 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
  }
})

逐项解读:

  • frameworks: ['mocha', 'chai']:注册 Mocha 与 Chai 适配器,实现全局断言 API;
  • files: ['./index.js'] + preprocessors:把入口文件交给 webpack 与 sourcemap 预处理,singleRun: true 表示测试结束后自动退出 Karma 进程(适合 CI);
  • customLaunchers.visibleElectron:基于 karma-electron 的 Electron 启动器定制,flags: ['--show'] 会在测试时显示 Electron 窗口,便于调试;
  • client.useIframe: false:Karma 测试页面不用 iframe 承载,而是直接在主窗口上下文中运行,这是 karma-electron 的推荐配置;
  • coverageReporter:输出 lcov 格式覆盖率报告到 ./coverage 目录,同时以 text-summary 在终端汇总显示;
  • reporters: ['spec', 'coverage']:使用 karma-spec-reporter 输出可读的用例明细,并叠加覆盖率报告。

依赖 Mock 与 inject-loader

electron-vue 默认安装了 inject-loader,用于对模块依赖进行注入式 Mock。其典型场景是:当组件依赖某个服务模块(如 API 请求层)时,测试中可以通过 inject-loader 注入替身实现,隔离外部副作用。由于它与 Vue 单文件组件(.vue)的配合方式与 vue-loader 的加载流程相关,具体用法可参考 vue-loader 的"测试与仿真(Testing with Mocks)"文档——核心思路是把组件源码中 import 的模块替换为测试替身,从而专注验证组件自身逻辑。

端到端测试:Spectron + Mocha 驱动真实应用

运行方式与前置条件

端到端测试的命令是:

npm run e2e

它实际执行的是 npm run pack && mocha test/e2e(见 template/package.json)。这里有一个重要的前置条件:在运行端到端测试之前,必须调用 npm run pack 来创建一个产品构建——因为 Spectron 需要以 dist/electron/main.js 作为应用入口来启动完整的 Electron 应用。pack 命令内部又会依次执行 pack:main 与 pack:renderer,分别用 Webpack 生产模式打包主进程与渲染进程(见 template/package.json)。

文件结构

脚手架生成的 test/e2e 目录结构如下:

my-project
├─ test
│  ├─ e2e
│  │  ├─ specs/
│  │  ├─ index.js
│  │  └─ utils.js

同样地,大多数情况下只需关注 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 }}')
      })
  })
})

这是脚手架自带的第一个端到端用例:启动应用后,通过 WebDriverIO 的 getTitle() 获取窗口标题,断言其与应用名一致(模板中 {{ name }} 会在脚手架时替换为真实项目名)。

index.js

Mocha 的入口文件,负责收集加载 specs/ 内的所有测试(见 template/test/e2e/index.js):

'use strict'

// Set BABEL_ENV to use proper env config
process.env.BABEL_ENV = 'test'

// Enable use of ES6+ on required files
require('babel-register')({
  ignore: /node_modules/
})

// Attach Chai APIs to global scope
const { expect, should, assert } = require('chai')
global.expect = expect
global.should = should
global.assert = assert

// Require all JS files in `./specs` for Mocha to consume
require('require-dir')('./specs')

它与单元测试的 index.js 在机制上有所不同:这里不是用 Webpack 打包,而是通过 babel-register 在 Node 进程中实时转译 ES2015,并通过 require-dir 把 specs/ 下的全部测试文件装载给 Mocha。同时它把 Chai 的 expect、should、assert 三个 API 显式挂载到全局作用域,这就是端到端测试中这些断言 API 全局可用的原因。

utils.js

提供 specs/ 中通用的生命周期工具函数,核心是封装 Electron 应用的创建与销毁(见 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 创建 Spectron 的 Application 实例,path 指向 Electron 可执行文件,args 传入打包产物 dist/electron/main.js 作为应用入口,然后调用 this.app.start() 启动应用;
  • afterEach 在用例结束后检测应用是否仍在运行,若在运行则调用 this.app.stop() 关闭应用,避免进程残留;
  • startTimeout 与 waitTimeout 均设置为 10000ms,控制应用启动与元素等待的超时阈值。

Spectron 的工作原理

Spectron 是 Electron 官方的端到端测试框架,其底层架构是:通过 ChromeDriver 驱动 Electron 内的 Chromium 引擎,并通过 WebDriverIO 提供的客户端 API 来操作 DOM 元素、窗口和应用状态。

WebDriverIO API 的使用

如 Spectron 官方文档所述,你可以通过 this.app.client 访问完整的 WebDriverIO API,例如 getTitle()、click()、getText()、waitForVisible() 等,用于模拟用户操作并断言应用行为。this.app.client 返回的是 Promise 链式接口,所以测试中通常写成:

return this.app.client.getTitle()
  .then(title => { ... })

一个关键的 Mocha 注意事项:慎用箭头函数

由于 electron-vue 的 e2e 测试运行在 Mocha 中,this 会在 beforeEach、afterEach 和 it 之间共享——这正是 utils.js 能把 app 挂在 this 上、而 Launch.spec.js 能在用例中通过 this.app.client 取到它的原因。因此文档特别强调:

ES2015 的箭头函数(arrow function)在某些情况下不能使用,因为箭头函数会覆盖 this 的语境(lexical this),导致 this.app 指向错误。

这也是模板中 describe 与 it 的回调全部使用普通 function () {} 写法(见 template/test/e2e/specs/Launch.spec.js)而不是箭头函数的原因。在编写自己的 e2e 用例时,务必沿用这一约定;单元测试由于不依赖 this 共享状态,使用箭头函数则没有问题(参见 template/test/unit/specs/LandingPage.spec.js)。

一键运行所有测试

当你同时选择了单元测试与端到端测试时,可以使用单条命令串联运行:

npm test

其等价于(见 template/package.json 中的模板逻辑):

npm run unit && npm run e2e

注意 && 的含义:只有单元测试全部通过,才会继续执行端到端测试。由于 npm run e2e 内部已包含 npm run pack 环节,这条命令链会自动完成"打包 → 单元测试 → 端到端测试"的完整流程。

CI 集成:在 Travis CI 与 AppVeyor 上跑测试

原理与适用范围

如果在脚手架阶段选择了 electron-builder 作为构建工具,那么你的项目可以在 Travis CI(构建 linux 与 darwin/macOS)和 AppVeyor(构建 win32)上轻松完成跨平台测试。在脚手架生成的 .travis.yml 与 appveyor.yml 中,测试部分默认是被注释掉的,你可以快速取消注释以启用测试。

以仓库中自带的 template/appveyor.yml 为例:

version: 0.1.{build}

branches:
  only:
    - master

image: Visual Studio 2017
platform:
  - x64

cache:
  - node_modules
  - '%APPDATA%\npm-cache'
  - '%USERPROFILE%\.electron'
  - '%USERPROFILE%\AppData\Local\Yarn\cache'

init:
  - git config --global core.autocrlf input

install:
  - ps: Install-Product node 8 x64
  - git reset --hard HEAD
  - yarn
  - node --version

build_script:
  #- yarn test
  - yarn build

test: off

可以看到模板第 1~4 行的注释块会根据你是否选择了测试来包裹配置,而 build_script 中被注释的 #- yarn test 就是预留的 CI 测试开关——取消注释即可让 AppVeyor 在构建前先运行整套测试。cache 段对 node_modules、npm 缓存、Electron 二进制缓存做了加速处理,值得在真实 CI 配置中保留。

启用 CI 测试的完整步骤

结合 docs/cn/using-electron-builder.md 中"使用 CI 的自动化部署"一节的说明,完整启用流程如下:

  1. 在 Travis CI 或 AppVeyor 上创建账户并添加你的仓库;
  2. 在 GitHub 的 Settings → Developer settings → Personal access tokens 中生成一个 token(同一个 token 可同时用于 Travis CI 与 AppVeyor);
  3. 在 Travis CI 或 AppVeyor 的仓库设置中添加 环境变量(Environment Variable)(如 GH_TOKEN);
  4. 取消 .travis.yml / appveyor.yml 中被注释的测试命令,推送代码到 master 分支触发构建。

CI 服务默认监听 master 分支的推送:推送后它们会克隆仓库并在干净环境中依次执行安装依赖、跑测试(启用后)、构建应用的流程;在部署场景下,electron-builder 读取到 GH_TOKEN 环境变量后还会把构建产物上传为 GitHub 发布草稿,供人工编辑后发布。

常见问题与实战建议

单元测试与端到端测试如何取舍

两条测试线的定位互补:

  • 单元测试(npm run unit)速度快、粒度细,直接运行在 Electron 渲染进程的测试环境里,适合对 Vue 组件、工具函数、Vuex store 模块做纯逻辑验证;
  • 端到端测试(npm run e2e)代价高但覆盖面完整,启动真实 Electron 应用,适合验证应用启动、窗口标题、路由跳转、关键用户流程等整体行为。

从 template/test/unit/specs/LandingPage.spec.js 与 template/test/e2e/specs/Launch.spec.js 两个模板用例可以直观看出差异:前者直接实例化 Vue 组件并断言渲染文本,后者则启动完整应用并读取真实窗口标题。

覆盖率数据的来源与定制

单元测试的覆盖率来自 karma.conf.js 中 babel-plugin-istanbul 与 karma-coverage 的配合(见 template/package.json 与 template/test/unit/karma.conf.js)。index.js 中 require.context('../../src/renderer', ...) 决定了哪些源码计入覆盖率,你可以通过修改这个正则来缩小或扩大统计范围。报告输出在 ./coverage 目录(lcov 格式)和终端(text-summary 格式)。

测试环境变量约定

整个测试体系中有一个贯穿始终的环境变量约定:BABEL_ENV 在单元测试配置(见 template/test/unit/karma.conf.js)与端到端入口(见 template/test/e2e/index.js)中均被设为 'test',用于让 Babel 加载测试专用的 preset 配置;同时单元测试通过 DefinePlugin 将 process.env.NODE_ENV 定义为 'testing'。在编写组件代码时,可以依据这些约定为测试环境准备专门的初始化逻辑,而不会污染生产构建。

小结

electron-vue 的测试体系由三条命令构成完整闭环:npm run unit(Karma + Mocha + Chai 驱动 renderer 进程单元测试)、npm run e2e(Spectron + Mocha 驱动真实应用端到端测试,内部自动先 npm run pack)、npm test(unit && e2e 串联全量回归)。其工程化核心在于:test/unit 借助 karma-webpack 复用渲染进程的 Webpack 配置并实现覆盖率统计;test/e2e 借助 babel-register + require-dir 收集用例,并通过 utils.js 统一管理 Spectron 应用生命周期。启用测试后,还可以在 .travis.yml 与 appveyor.yml 中取消注释相关配置,把测试接入跨平台 CI 流水线。

更多细节可进一步阅读仓库中的相关文档:单元测试、端到端测试 与 使用 electron-builder,并结合脚手架模板 template/test/unit 与 template/test/e2e 中的真实代码加深理解。

登录后查看全文
electron-vue