Enzyme 3.x 搭配 React 0.14 的完整安装与配置指南(enzyme-adapter-react-14)
Enzyme 3.x 搭配 React 0.14 的完整安装与配置指南(enzyme-adapter-react-14)
本指南讲解如何在 React 0.14 项目中安装并配置 Enzyme(本仓库当前主版本为 3.x 系列,核心包 enzyme/package.json 版本为 3.11.0),涵盖 react、react-dom、react-addons-test-utils 三个前置依赖与 enzyme-adapter-react-14 适配器的安装命令、ES6/ES5 两种风格的初始化配置,以及首个测试文件的编写。读完本文,你将能在 React 0.14 环境中完整跑通 Enzyme 的 shallow / mount / render 三种渲染模式,并理解适配器在底层如何工作。
为什么 React 0.14 需要单独的安装步骤
Enzyme 3.x 引入了「适配器(Adapter)」架构:Enzyme 核心本身不再直接依赖某个具体版本的 React,而是通过 configure({ adapter }) 注入与当前 React 版本匹配的适配器来驱动渲染。因此,不同 React 版本需要安装不同的适配器包。
对于 React 0.14 这个较老的版本,除了 react 与 react-dom 之外,还必须额外安装测试工具附加包 react-addons-test-utils——这是 0.14 时代提供 TestUtils 的唯一途径,Enzyme 的浅渲染(shallow rendering)与事件模拟(simulate)都依赖它。这一点从适配器源码中可以直接得到印证:在 ReactFourteenAdapter.js 中,适配器同时 import 了 ReactDOM、ReactDOMServer 和 react-addons-test-utils 的 TestUtils;其 package.json 也将 react、react-dom、react-addons-test-utils 一并声明为 peerDependencies(版本均为 ^0.14.0,同时要求 enzyme 为 ^3.0.0)。
第一步:安装 React 0.14 与 react-dom
如果项目尚未安装 React 0.14 与配套的 react-dom,请执行:
npm i --save react@0.14 react-dom@0.14
--save(等价于-S)会将两个包写入dependencies,因为是运行时依赖。- 版本号固定为
0.14,npm 会解析到 0.14.x 的最新补丁版本。切勿混装其他大版本,否则适配器将无法与 React 内部结构匹配。
第二步:安装测试工具附加包 react-addons-test-utils
React 0.14 时期的测试工具不在 react-dom 中,而是一个独立的 addons 包,必须单独安装:
npm i --save-dev react-addons-test-utils@0.14
- 这里使用
--save-dev(等价于-D),因为它只在测试阶段使用。 - 该包是 Enzyme 浅渲染器的直接依赖:适配器的
createShallowRenderer通过TestUtils.createRenderer()创建渲染器(见 ReactFourteenAdapter.js),mount模式的事件模拟则通过TestUtils.Simulate触发(见 ReactFourteenAdapter.js)。
第三步:安装 enzyme 与 React 0.14 适配器
安装 Enzyme 本体及对应的版本适配器:
npm i --save-dev enzyme enzyme-adapter-react-14
两个包都应作为开发依赖安装。其中:
enzyme是核心库,提供shallow、mount、render三个渲染入口与ReactWrapper、ShallowWrapper等封装(见 src/index.js)。enzyme-adapter-react-14是专门面向 React 0.14 的适配器。其包入口 index.js 直接导出ReactFourteenAdapter类。
第四步:在 setup 文件中配置适配器
Enzyme 3 要求在任何测试运行前先通过 configure({ adapter }) 注册适配器,否则会抛出错误。建议把配置放在独立的 setup 文件中,在测试运行器(如 mocha、jest、karma)启动时最先执行。
ES6 写法
// setup file
import { configure } from 'enzyme';
import Adapter from 'enzyme-adapter-react-14';
configure({ adapter: new Adapter() });
ES5 写法
// setup file
var enzyme = require('enzyme');
var Adapter = require('enzyme-adapter-react-14');
enzyme.configure({ adapter: new Adapter() });
configure 实际上执行的是配置合并逻辑:在 configuration.js 中,merge 会先对传入的 adapter 调用 validateAdapter 做合法性校验(校验逻辑见 validateAdapter.js),校验通过后再 Object.assign 合并进全局配置。因此这里传入的必须是 new Adapter() 的实例。
第五步:编写并运行第一个测试
配置完成后,测试文件中即可直接引入 Enzyme 的渲染入口。以下两段代码与官方安装文档一致,分别演示 ES6 与 ES5 的最小用法:
// test file
import { shallow, mount, render } from 'enzyme';
const wrapper = shallow(<Foo />);
// test file
var enzyme = require('enzyme');
var wrapper = enzyme.shallow(<Foo />);
其中:
shallow(<Foo />)对组件做浅渲染,只渲染Foo自身,不渲染其子组件,是单元测试最常用的模式;mount(<Foo />)做完整挂载渲染,要求测试环境存在 DOM(详见下文「注意事项」);render(<Foo />)做静态渲染,输出 HTML 字符串(内部走ReactDOMServer)。
三种模式在适配器中分别对应 EnzymeAdapter.MODES.MOUNT / SHALLOW / STRING 三个分支(见 ReactFourteenAdapter.js),适配器根据 options.mode 决定使用哪种渲染器。
适配器底层原理与源码佐证
enzyme-adapter-react-14 的核心实现在 ReactFourteenAdapter.js,它对三种渲染模式的处理方式如下:
- 浅渲染(SHALLOW):基于
TestUtils.createRenderer()(L165-L166)。对于 DOM 元素直接透传;对于自定义组件,则通过getRenderOutput()取得渲染输出,并把 React 实例挂到instance字段上(L228-L242)。 - 完整挂载(MOUNT):调用
assertDomAvailable('mount')检查 DOM 是否可用,随后把组件包进一个 Mount Wrapper 并用ReactDOM.render挂载到attachTo指定的节点(默认创建一个新的div),见 L101-L119。取消挂载则通过ReactDOM.unmountComponentAtNode完成。 - 静态渲染(STRING):使用
ReactDOMServer.renderToStaticMarkup输出无 data-react 属性的静态 HTML(L261-L275)。
此外,该适配器在构造时配置了两个 0.14 时代特有的生命周期选项(L84-L98):
componentDidUpdate支持prevContext参数(supportPrevContextArgumentOfComponentDidUpdate: true);getChildContext由渲染器调用(calledByRenderer: true),legacyContextMode为'parent'。
这些细节说明,Enzyme 通过适配器层弥合了不同 React 版本在生命周期、Context 与事件系统上的差异。
如何确认当前 React 版本对应哪个适配器
如果项目里同时维护多个 React 版本的测试环境,可以参考本仓库的版本映射逻辑 getAdapterForReactVersion.js:^0.14.0 范围映射到 enzyme-adapter-react-14,^0.13.0 映射到 enzyme-adapter-react-13,15/16 系列则分别映射到 enzyme-adapter-react-15(.4) 与 enzyme-adapter-react-16.x 等。
Enzyme 自身的测试套件正是这样做的:测试辅助脚本 adapter.js 会根据当前加载的 React 版本自动 require 对应适配器(^0.14 时加载 enzyme-adapter-react-14),再在 setupAdapters.js 中统一调用 Enzyme.configure({ adapter: new Adapter() })。这套「按版本选适配器 → 集中配置」的模式,值得作为你多版本测试基建的参考。
注意事项与常见问题
- mount 需要 DOM 环境:
mount模式会执行真实的ReactDOM.render,因此在 Node 环境跑测试时需要先搭建 DOM(如 jsdom),否则适配器会在assertDomAvailable('mount')处报错。仓库的 jsdom 指南 与 mocha 指南 提供了相关配置说明。 - 三个前置依赖版本必须统一为 0.14:
react、react-dom、react-addons-test-utils三者内部结构相互耦合,混用不同大版本会导致渲染或事件模拟异常。适配器的 peerDependencies(见 enzyme-adapter-react-14/package.json)已经明确约束了这一点。 - React 0.14 不支持新生命周期:Hooks、
getDerivedStateFromProps等新特性在 0.14 中不存在,适配器按 0.14 的旧式生命周期(如componentWillReceiveProps)工作,相关逻辑见 ReactFourteenAdapter.js。
其他 React 版本的对应安装入口
本仓库在 安装总览 中按版本分列了安装指南,可作为横向对照:
- React 16 安装指南(适配器
enzyme-adapter-react-16) - React 15 安装指南(适配器
enzyme-adapter-react-15,需另装react-test-renderer@15) - React 0.13 安装指南(适配器
enzyme-adapter-react-13,无需react-dom与 test-utils)
各指南的整体流程一致:安装对应版本的 React 依赖 → 安装 enzyme 与版本适配器 → 在 setup 文件中 configure → 在测试文件中导入 shallow / mount / render。