Enzyme 与 React 15 集成实战:安装、Adapter 配置与测试入门

原创2026-09-20 12:34:351,892 阅读
文章标签:测试前端

Enzyme 与 React 15 集成实战:安装、Adapter 配置与测试入门

本指南聚焦于在 React 15 项目中使用 Enzyme 编写组件测试的完整落地流程,覆盖 react@15、react-dom@15、react-test-renderer@15 与 enzyme-adapter-react-15 的安装组合、ES6/ES5 两种配置方式,以及首个测试用例的编写与运行。读完本文,你将能在 React 15 环境下独立搭建一套可用的 Enzyme 测试环境,并理解版本匹配与 Adapter 配置背后的原理。

React 15 时代的安装特殊性

React 15 是 Enzyme 官方支持的一个重要版本分支。与 React 16 及更高版本不同,在 React 15 下使用 Enzyme 需要额外安装测试工具 addon(react-test-renderer),这是因为当时 React 的测试工具已经从 react-addons-test-utils 拆分并迁移到独立的 react-test-renderer 包中。Enzyme 的官方安装文档(见 docs/installation/README.md)按 React 主版本划分了独立的安装章节,本文即对应其中的 React 15 部分(仓库文档原文位于 docs/installation/react-15.md)。

需要特别说明的是,Enzyme 3.x 对 React 15 的适配又细分为两个版本:

  • React 15.5 及以上:使用 enzyme-adapter-react-15;
  • React 15.0 ~ 15.4.x:使用 enzyme-adapter-react-15.4。

这一对应关系在仓库的 packages/enzyme-adapter-react-helper/src/getAdapterForReactVersion.js 中通过 semver 区间精确声明:^15.5.0 映射到 enzyme-adapter-react-15,而 15.0.0 - 15.4.x 映射到 enzyme-adapter-react-15.4。15.5 是 React 的重要分水岭(React.PropTypes 被迁移至独立的 prop-types 包),因此下文默认以 React 15.5+ 为例,若你的项目停留在 15.0~15.4,只需将 adapter 包名替换为 enzyme-adapter-react-15.4 即可。

第一步:安装 React 15 与 react-dom

如果项目中还没有 React 15 和 react-dom,请先以运行时依赖(--save)的方式安装:

npm i --save react@15 react-dom@15

这两者是 React 组件渲染与 DOM 操作的基础,Enzyme 的 mount(完整挂载渲染)模式直接依赖 react-dom。从 packages/enzyme-adapter-react-15/package.json 的 peerDependencies 可以看到,enzyme-adapter-react-15 要求:

"peerDependencies": {
  "enzyme": "^3.0.0",
  "react": "^15.5.0",
  "react-dom": "^15.5.0",
  "react-test-renderer": "^15.5.0"
}

也就是说,react、react-dom、react-test-renderer 三者必须是配套的 15.5+ 版本,并且 enzyme 主包需要 3.0.0 以上。

第二步:安装测试工具 react-test-renderer

在 React 15 中,Enzyme 的浅渲染(shallow)依赖 react-test-renderer/shallow 提供的 ShallowRenderer。这一点可以直接从源码得到印证:在 packages/enzyme-adapter-react-15/src/ReactFifteenAdapter.js 的第 8 行,适配器通过 import ShallowRenderer from 'react-test-renderer/shallow' 引入浅渲染器,并在 createShallowRenderer 方法中实例化使用。

因此,请以开发依赖(--save-dev)方式安装测试工具:

npm i --save-dev react-test-renderer@15

注意,这里必须是 @15 版本,与 React 主版本严格对齐;版本错配会导致浅渲染内部接口不兼容。

第三步:安装 Enzyme 与 React 15 适配器

接下来安装 Enzyme 主包以及对应的 React 15 适配器:

npm i --save-dev enzyme enzyme-adapter-react-15

Enzyme 3.x 采用"适配器(Adapter)"架构:核心包 enzyme 只提供统一的测试 API(shallow、mount、render、configure 等),具体的 React 版本差异全部由对应版本的 adapter 封装。从 packages/enzyme/src/index.js 可以看到,enzyme 主包对外导出 ReactWrapper、ShallowWrapper、EnzymeAdapter、mount、shallow、render 和 configure(即 configuration.js 中的 merge)。

而 enzyme-adapter-react-15 包本身非常轻量,其入口文件 packages/enzyme-adapter-react-15/src/index.js 只有一行:

module.exports = require('./ReactFifteenAdapter');

真正的实现逻辑(mount/shallow/string 三种渲染器的创建、事件模拟、生命周期选项配置等)都在 ReactFifteenAdapter.js 中,它继承了 enzyme 的 EnzymeAdapter 基类。

第四步:配置 Adapter(ES6 与 ES5)

安装完成后即可投入使用。在使用 enzyme 的任何顶层 API 之前,必须先通过 configure 注入适配器。官方文档给出了 ES6 与 ES5 两种写法,建议将配置放在独立的 setup 文件 中,并在测试运行前加载。

ES6 写法

setup 文件:

// setup file
import { configure } from 'enzyme';
import Adapter from 'enzyme-adapter-react-15';

configure({ adapter: new Adapter() });

测试文件:

// test file
import { shallow, mount, render } from 'enzyme';

const wrapper = shallow(<Foo />);

ES5 写法

setup 文件:

// setup file
var enzyme = require('enzyme');
var Adapter = require('enzyme-adapter-react-15');

enzyme.configure({ adapter: new Adapter() });

测试文件:

// test file
var enzyme = require('enzyme');

var wrapper = enzyme.shallow(<Foo />);

configure 做了什么

configure 在源码层面对应 packages/enzyme/src/configuration.js 中的 merge 函数:它会把传入的配置(如 adapter)合并进全局配置对象。关键细节是,如果传入的 extra.adapter 存在,会先调用 validateAdapter 进行校验,再执行 Object.assign(configuration, extra)。

校验逻辑见 packages/enzyme/src/validateAdapter.js,它依次检查:

  1. 未传入 adapter 时报错(提示必须先 Enzyme.configure({ adapter: new Adapter() }));
  2. 传入的是 adapter 构造函数(function)而不是实例时报错——因此代码中必须写 new Adapter(),绝不能漏掉 new;
  3. adapter 实例必须继承自 EnzymeAdapter 基类。

这也是文档示例中始终使用 new Adapter() 的原因所在。如果你在测试启动时报出 "Enzyme expects an adapter to be configured, but found none" 之类的错误,多半是 setup 文件没有被测试运行器加载,或 adapter 传入了构造函数而非实例。

编写并运行第一个测试

完成配置后,就可以在测试文件中编写 React 15 组件的测试了。以 mocha + BDD 风格 chai 为例(这是仓库文档推荐的测试组合,见 docs/installation/README.md,不过 enzyme 本身并不依赖任何特定测试框架,任何测试运行器都适用):

// test/Foo.spec.jsx
import React from 'react';
import { expect } from 'chai';
import { shallow } from 'enzyme';
import Foo from '../src/Foo';

describe('<Foo />', () => {
  it('renders its title prop as text', () => {
    const wrapper = shallow(<Foo title="Hello Enzyme" />);
    expect(wrapper.text()).to.contain('Hello Enzyme');
  });

  it('simulates click events', () => {
    const wrapper = shallow(<Foo />);
    wrapper.find('button').simulate('click');
    expect(wrapper.state('clicked')).to.equal(true);
  });
});

运行测试:

npx mocha --require @babel/register --require ./test/setup.js test/**/*.spec.jsx

其中 setup.js 即第四步中的 adapter 配置文件。shallow、mount、render 三种渲染模式分别对应适配器中的三种渲染器(见 ReactFifteenAdapter.js 中的 createShallowRenderer、createMountRenderer、createStringRenderer):

  • shallow:使用 react-test-renderer/shallow 的 ShallowRenderer,只渲染组件本身,不渲染子组件,速度最快;
  • mount:基于 react-dom 完整渲染到真实 DOM(node 环境需配合 jsdom),支持完整的生命周期与事件模拟;
  • render:基于 react-dom/server 的 renderToStaticMarkup 输出静态 HTML,适合做结构断言。

版本与适配器对照速查

为便于排查安装问题,这里汇总 React 15 相关版本组合:

React 版本区间 需要安装的 adapter 测试工具
15.5 ~ 15.x enzyme-adapter-react-15 react-test-renderer@15
15.0 ~ 15.4.x enzyme-adapter-react-15.4 react-test-renderer@15

适配器与 React 版本区间的映射规则由 getAdapterForReactVersion.js 统一维护,Enzyme 的辅助测试包正是通过这套规则为不同 React 版本自动选择对应 adapter。若版本不匹配(例如在 React 15.4 下使用 enzyme-adapter-react-15),会出现 React 内部结构读取异常、浅渲染行为不一致等问题。

常见问题排查

  1. "Enzyme expects an adapter to be configured, but found none":确认 setup 文件被测试运行器加载,且 configure({ adapter: new Adapter() }) 在任何 shallow/mount/render 调用之前执行。
  2. "Enzyme expects an adapter instance... you provided an adapter constructor":检查是否漏写了 new,configure 接收的必须是实例。
  3. 浅渲染报内部错误:确认 react-test-renderer 与 react 主版本一致(均为 15.x),并检查 React 小版本是否与 adapter 区间匹配(15.0~15.4 请改用 enzyme-adapter-react-15.4)。
  4. mount 在 Node 环境报 DOM 相关错误:mount 需要真实的 DOM 环境,在 Node 下请先引入 jsdom 配置(参考仓库 docs/guides/jsdom.md 的说明)。

小结

在 React 15 项目中使用 Enzyme 的关键路径可以概括为:安装配套的 react@15、react-dom@15 与 react-test-renderer@15,安装 enzyme 与 enzyme-adapter-react-15(15.0~15.4 用 -15.4),然后在 setup 文件中通过 configure({ adapter: new Adapter() }) 完成初始化,最后在测试文件中使用 shallow、mount、render 编写断言。理解 Adapter 的版本匹配机制与 configure 的校验流程,就能快速定位绝大多数安装与配置阶段的问题。

登录后查看全文
enzyme