组件的测试

组件库测试的目标，不是“为了有测试而测试”，而是为了回答几个更具体的问题：

• 组件在真实使用方式下能不能正常工作
• 改动之后有没有把已有行为改坏
• 交互、样式、类型和打包后的使用体验是否稳定

如果把这些问题说清楚，组件测试的层次就会自然清晰很多。

先有一个基本原则

不要把所有验证都压到单一工具上。

一个更稳的组件库测试策略通常是分层的：

1. 文档或示例站验证“能不能被真实使用”
2. 单元测试验证“核心行为对不对”
3. E2E / 视觉测试验证“浏览器层面的交互和样式是否稳定”

如何测试

其实测试自己的组件库并不复杂，最直接的方式就是在项目或组件库文档中直接引入它。

直接测试

这里以一个典型的 vite 应用项目为例：

ui
 - src # 示例应用
 - lib # 组件库源码
 - test # 测试代码
 - index.html
 - vite.config.ts
 - vitest.config.ts
 - package.json

这里把应用相关代码放在 src，组件库放在 lib，测试代码放在 test。

这样你使用 vite 启动本地服务器时，入口依然是 src/main.ts，但你可以在示例页面里直接消费 lib 下的组件。

这种方式的好处是：

• 反馈很快
• 最接近真实使用方式
• 适合先发现 API 和交互设计是否顺手

用文档站做“活文档测试”

vitepress

快速初始化一个 VitePress 文档站，把组件示例、安装方式、API 说明放进去。

它的价值不只是写文档，还包括：

• 示例代码会真的被运行
• 文档演示能反过来暴露组件问题
• 每次组件改动都能顺手验证展示效果

对很多中小型组件库来说，文档站本身就是一层非常高性价比的验证环境。

storybook

借助 Storybook，你可以为每个组件创建一个可交互的 Story，并配合插件实现更系统的交互测试。

它比简单文档站更强的一点在于：它天然提供了组件隔离环境。

这意味着：

• 不容易被业务页面上下文干扰
• 更适合枚举不同 props / slot / 状态组合
• 更适合做视觉回归、交互回放和可访问性检查

如果组件库规模较大、状态组合多、多人协作频繁，Storybook 往往比单纯 VitePress 更适合长期维护。

单元测试

单元测试的重点不是把每一行代码都覆盖，而是保护那些“容易退化但肉眼不一定马上看出来”的行为。

这里只需要使用 vitest 即可，这是 Vue 官方生态里最自然的选择。

同样可以分为 Vue 3 主线与 Vue 2 历史兼容两种情况。

Vue 3

安装最新版的：

• @vue/test-utils
• @testing-library/vue

一般来说：

• @vue/test-utils 更适合组件实例级测试
• @testing-library/vue 更适合从用户视角验证界面行为

Vue 2

Vue 2 已进入 EOL，本节仅用于维护历史项目。

安装：

• @vue/test-utils@legacy
• @testing-library/vue@^5

legacy 对应的是 v1，用于 Vue 2。

官方文档：

https://test-utils.vuejs.org/

什么时候应该补单元测试

一个务实的判断标准是：

一开始先测核心路径

先覆盖：

• 关键 props 行为
• 关键事件触发
• 插槽渲染
• 条件渲染与禁用态

出现 bug 时再补回归用例

后续如果线上或使用方反馈 bug，就在修复时补上：

• 旧行为的回归测试
• 新修复场景的边界测试

这样测试会和真实维护成本对齐，而不是一开始就把自己拖进低价值覆盖率竞赛。

E2E 测试以及视觉测试

E2E（End-to-End）测试用于模拟用户的真实操作流程，从浏览器层面验证组件是否按预期工作。

它测试的不只是组件行为，还包括它们在真实运行环境中的集成方式。

比如 Playwright 就是一个很合适的现代 E2E 工具，支持：

• 多浏览器测试
• 并发执行
• 自动截图和录像
• 更接近真实用户操作的交互流程

视觉测试为什么重要

组件库里有大量问题，其实不是功能错了，而是“看起来不对了”：

• 间距变了
• 主题变量失效了
• hover / active 状态不对
• 暗色模式或尺寸变体样式跑偏

这类问题单靠单元测试通常抓不住，所以视觉测试很有价值。

Playwright 的截图对比能力就是一个很直接的方案。

一个更实用的测试顺序

如果资源有限，建议优先级按这个顺序走：

1. 先有可运行的示例页或文档站
2. 再补核心行为的单元测试
3. 最后给高风险组件加 E2E / 视觉回归

这比一开始就追求“大而全”的测试体系更务实。

测什么，比用什么更重要

对组件库来说，优先保护这些东西：

• 公共 API 是否稳定
• 用户能否完成核心交互
• 常见状态切换是否正确
• 样式是否出现明显回归
• 打包后消费者是否还能正常引入

只要这些被稳稳保护住，测试体系就已经很有价值了。