当前位置：首页 > news >正文

为React组件库引入自动化测试：从零到完善的实践之路

news 2025/5/6 13:05:56

为什么我们需要测试？

我们的React+TypeScript业务组件库已经稳定运行了一段时间，主要承载各类UI展示组件，如卡片、通知等。项目初期，迫于紧张的开发周期，我们暂时搁置了自动化测试的引入。当时团队成员对组件逻辑了如指掌，即便没有测试也能游刃有余。

然而随着时间推移，问题逐渐显现。当新成员加入或老组件需要迭代时，我们常常陷入两难：修改代码可能破坏原有功能，但不修改又无法满足新需求。特别是在处理那些具有多种交互状态的复杂组件时，手动测试变得既耗时又不可靠。这时，引入自动化测试的必要性就凸显出来了。

搭建测试环境

依赖安装

我们首先从安装核心测试依赖开始，这些工具将构成我们测试体系的基础框架：

测试运行核心：jest和jsdom环境包
TypeScript支持：确保类型安全的测试环境
React测试工具：专门为React组件设计的测试工具链

npm install jest jest-environment-jsdom @types/jest ts-jest @testing-library/react @testing-library/jest-dom @testing-library/user-event --save-dev

配置Jest

创建jest.config.ts配置文件时，有几个关注点：

针对TypeScript项目的特殊处理
浏览器环境的模拟
测试初始化流程
文件转换规则

module.exports = {preset: "ts-jest", // 为 TypeScript 项目准备的 Jest 配置预设testEnvironment: "jsdom", // 测试运行在模拟的浏览器环境中setupFilesAfterEnv: ["<rootDir>/jest.setup.ts"], // 指定在测试环境初始化后立即执行的文件transform: {"^.+\\.(ts|tsx)$": "ts-jest", // 使用 ts-jest 处理所有 .ts 和 .tsx 文件},testPathIgnorePatterns: ["/node_modules/", "/dist/"], // 忽略指定目录下的测试文件moduleFileExtensions: ["ts", "tsx", "js", "jsx", "json", "node"], // 定义 Jest 能识别的模块文件扩展名
};export {}; // 使文件成为模块

创建jest.setup.ts文件引入断言库：

import "@testing-library/jest-dom";

TypeScript配置

修改tsconfig.json包含测试相关文件：

{"include": ["src","jest.config.ts","jest.setup.ts","__mocks__/**/*.ts"]
}

测试用例编写

我们以一个通知组件为例，该组件有两种UI形态：

标题和描述组合的时间内容文案提示
带有喇叭图标的提示，点击关闭按钮时调用接口保存用户状态

在这里插入图片描述

特殊依赖处理

组件中有三类特殊引入需要处理：

import './index.less';
import { noticeIcon, closeIcon } from "$src/common/icon";
import request from "$src/request";

1、处理 CSS/LESS 资源
Jest 默认无法解析 CSS/LESS 文件，我们可以通过配置将其模拟为空对象：

// jest.config.js
module.exports = {moduleNameMapper: {"\\.(less|css)$': '<rootDir>/__mocks__/styleMock.ts", // 指向一个空文件},
};// __mocks__/styleMock.ts
module.exports = {};

2、配置路径别名
对于 $src 这样的路径别名，需要在 Jest 配置中映射：

// jest.config.js
module.exports = {moduleNameMapper: {'^\\$src/(.*)$': '<rootDir>/src/$1',},
};

3、模拟图标资源
对于图标这类静态资源，我们可以在测试文件中直接模拟：

// __tests__/index.test.tsx
jest.mock('$src/common/icon', () => ({noticeIcon: 'notice-icon-path',closeIcon: 'close-icon-path',
}));

4、模拟 API 请求

对于网络请求模块，我们可以将其转换为 Jest 模拟函数：

// __tests__/index.test.tsx
import request from '$src/request';const mockedRequest = request as jest.MockedFunction<typeof request>;jest.mock('$src/request', () => ({__esModule: true, // 标识这是 ES Moduledefault: jest.fn(() => Promise.resolve({ data: {} })),
}));

通过以上配置，我们能够有效地隔离组件测试环境，专注于组件逻辑本身的测试，而不受样式、静态资源和网络请求等外部因素的影响。

基础测试框架搭建

我们首先建立测试的基本结构：

describe("Notification组件", () => {// 公共props定义const baseProps = {body: {},tokenId: "test-token",urlPrefix: "https://api.example.com",};// 每个测试用例前的清理工作beforeEach(() => {jest.clearAllMocks();mockedRequest.mockReset();});
});

核心测试场景覆盖

在配置好 Jest 测试环境后，我们将针对通知组件编写全面的测试用例。该组件具有两种展示形态和交互逻辑，我们将从四个关键维度进行测试覆盖：

1、边界情况测试

我们首先考虑最极端的场景——当传入无效props时，组件是否能够优雅处理：

it("当传入无效body时应安全地返回null", () => {const { container } = render(<Notification {...baseProps} body={null} />);expect(container.firstChild).toBeNull();
});

2、日期类型展示验证
对于日期类型的通知，我们需要确认：

关键文本是否正确渲染
DOM结构是否符合预期
样式类是否准确应用

it("应正确渲染日期类型通知", () => {render(<Notification {...dateProps} />);expect(screen.getByText("今日公告")).toBeInTheDocument();expect(screen.getByText("2023-06-15")).toBeInTheDocument();const dateContainer = screen.getByText("今日公告").parentElement;expect(dateContainer).toHaveClass("notice-header-date");
});

3、广播类型交互测试

广播通知的测试更加复杂，需要验证：

初始状态下的元素展示
图标资源是否正确加载
点击关闭后的行为

describe("BROADCAST_TYPE 类型", () => {const broadcastProps = {...baseProps,body: {type: BROADCAST_TYPE,content: "重要通知内容",closeUrl: "/close-notice",},};it("初始状态下应该显示广播内容", () => {render(<Notification {...broadcastProps} />);// 验证内容expect(screen.getByText("重要通知内容")).toBeInTheDocument();// 验证图片const images = screen.getAllByRole("img");expect(images[0]).toHaveAttribute("src", "notice-icon-path");expect(images[1]).toHaveAttribute("src", "close-icon-path");// 验证类名const broadcastContainer = screen.getByText("重要通知内容").closest(".h5link-notice-header-broadcast");expect(broadcastContainer).toBeInTheDocument();});it("点击关闭按钮后应该隐藏广播内容", () => {render(<Notification {...broadcastProps} />);// 找到关闭按钮（假设是最后一个img元素）const closeButton = screen.getAllByRole("img")[1].parentElement;fireEvent.click(closeButton!);expect(screen.queryByText("重要通知内容")).not.toBeInTheDocument();});
});

4、网络请求场景全覆盖
对于涉及API调用的场景，我们设计了多维度测试：

正常请求流程
无请求场景请求
失败处理
请求中的状态管理

describe("网络请求测试", () => {const broadcastPropsWithCloseUrl = {...baseProps,body: {type: BROADCAST_TYPE,content: "重要通知内容",closeUrl: "/close-notice",},};const broadcastPropsWithoutCloseUrl = {...baseProps,body: {type: BROADCAST_TYPE,content: "重要通知内容",// 没有closeUrl},};it("点击关闭时应该发送请求", async () => {// 模拟请求成功mockedRequest.mockResolvedValue({ data: {} });render(<Notification {...broadcastPropsWithCloseUrl} />);const closeButton = screen.getAllByRole("img")[1].parentElement;await act(async () => {fireEvent.click(closeButton!);});//验证请求参数expect(request).toHaveBeenCalledWith({url: "https://api.example.com/close-notice",method: "post",data: {},headers: {tokenId: "test-token",},});// 验证UI更新expect(screen.queryByText("重要通知内容")).not.toBeInTheDocument();});it("当没有closeUrl时不发送请求", async () => {render(<Notification {...broadcastPropsWithoutCloseUrl} />);const closeButton = screen.getAllByRole("img")[1].parentElement;await act(async () => {fireEvent.click(closeButton!);});expect(request).not.toHaveBeenCalled();// 验证UI仍然会更新expect(screen.queryByText("重要通知内容")).not.toBeInTheDocument();});it("请求失败时仍然关闭通知", async () => {// 模拟请求失败mockedRequest.mockResolvedValue(new Error("Request failed"));render(<Notification {...broadcastPropsWithCloseUrl} />);const closeButton = screen.getAllByRole("img")[1].parentElement;await act(async () => {fireEvent.click(closeButton!);});// 验证即使请求失败，UI也会更新expect(screen.queryByText("重要通知内容")).not.toBeInTheDocument();expect(request).toHaveBeenCalled();});it("请求期间UI应保持响应", async () => {// 创建一个未立即resolve的Promiselet resolveRequest: any;const promise = new Promise((resolve) => {resolveRequest = resolve;});mockedRequest.mockReturnValue(promise);render(<Notification {...broadcastPropsWithCloseUrl} />);const closeButton = screen.getAllByRole("img")[1].parentElement;// 第一次点击fireEvent.click(closeButton!);// 验证UI已立即更新expect(screen.queryByText("重要通知内容")).not.toBeInTheDocument();// 完成请求await act(async () => {resolveRequest({ data: {} });});
});

测试执行与覆盖率

基础测试执行

在完成通知组件的测试用例编写后，可以在 package.json 中配置测试脚本：

{"scripts": {"test": "jest"}
}

执行 npm run test 命令后，如下图所示，Jest 会在终端输出测试结果，包括：

测试文件数量
通过的测试用例数
失败的测试用例详情（包含错误堆栈信息）

在这里插入图片描述

覆盖率报告配置

为了更全面地评估测试质量，可以通过修改 jest.config.ts 启用覆盖率统计：

module.exports = {collectCoverage: true, // 启用覆盖率收集coverageDirectory: "coverage", // 指定覆盖率报告的输出目录coverageReporters: ["text", "html", "lcov", "clover"], //指定生成的覆盖率报告格式coverageThreshold: {// 设置覆盖率的最低阈值，如果未达标，Jest 会报错global: {// 全局覆盖率要求branches: 80,functions: 80,lines: 80,statements: 80,},"./src/components/**/*.tsx": {// 针对特定目录/文件设置更高要求branches: 90,functions: 90,lines: 90,statements: 90,},},
}