Enzyme ReactWrapper `.update()` API 深度解析：让组件树快照与真实 DOM 保持同步

Enzyme ReactWrapper.update()API 深度解析：让组件树快照与真实 DOM 保持同步

【免费下载链接】enzymeJavaScript Testing utilities for React项目地址: https://gitcode.com/gh_mirrors/en/enzyme

在 React 集成测试中，Enzyme 的mount()返回的ReactWrapper本质上持有一份组件树的快照。当组件状态被绕过 Enzyme 的 API 改变（异步setState、外部回调、setImmediate触发的事件等）时，这份快照就会与真实 DOM 脱节。本文围绕官方 API 文档 .update() 展开，完整讲解.update()的用途、三条关键注意事项、官方示例，并结合 packages/enzyme/src/ReactWrapper.js 的源码剖析"快照同步"在底层是如何实现的、为什么它永远不会强制重渲染，以及在 Hooks 测试场景中何时必须手动调用它。

什么是.update()

根据 API 文档，.update() => Self的官方定义是：

Syncs the enzyme component tree snapshot with the react component tree. Useful to run before checking the render output if something external may be updating the state of the component somewhere.

也就是说，.update()做的事情非常单一：把 Enzyme 内部缓存的组件树快照，与 React 实际渲染出的组件树重新对齐。它的典型使用场景是：在你断言渲染输出之前，有任何"外部因素"可能已经修改了组件状态，此时先调用.update()，再执行find()/text()/html()等查询，得到的才是当前真实输出。

返回值为ReactWrapper本身（返回this），因此支持链式调用。

官方文档给出了三条必须牢记的注意事项（NOTE）：

1. 无论你在哪个 wrapper 实例上调用，它永远更新的是 root；
2. 它只更新 Enzyme 对已渲染树的表示，不触碰 React 本身；
3. 它不触发重渲染。若你确实想强制重渲染，应使用wrapper.setProps({})（见 setProps）。

官方示例：完整可运行

以下示例完整继承自官方文档，演示了"通过外部调用instance()方法改变状态后，必须先update()才能断言新输出"这一核心用法：

class UpdateEnzyme extends React.Component { constructor(props) { super(props); this.state = { count: 0, }; this.increment = this.increment.bind(this); } increment() { const { count } = this.state; this.setState({ count: count + 1 }); } render() { const { count } = this.state; return <button type="button" className="increment" onClick={this.increment}>{count}</button>; } }

const wrapper = mount(<UpdateEnzyme />); expect(wrapper.find('button.increment').text()).to.equal('0'); wrapper.instance().increment(); // Update Enzyme's view of output wrapper.update(); expect(wrapper.find('button.increment').text()).to.equal('1');

示例中的关键点在于：wrapper.instance().increment()是绕过 Enzyme 直接调用组件实例方法的，React 内部确实执行了setState并重渲染了，但 Enzyme 的快照不会自动感知这次变化。若跳过中间的wrapper.update()，第二个断言拿到的仍是旧的'0'。这正是.update()存在的意义。

源码剖析：update()是如何同步快照的

update()的实现在 ReactWrapper.js，核心逻辑只有四步：

update() { const root = this[ROOT]; if (this !== root) { return root.update(); } privateSetNodes(this, this[RENDERER].getNode()); this[LINKED_ROOTS].forEach((linkedRoot) => { if (linkedRoot !== this[UPDATED_BY]) { linkedRoot[UPDATED_BY] = this; try { linkedRoot.update(); } finally { linkedRoot[UPDATED_BY] = null; } } }); return this; }

逐段对应文档中的三条 NOTE：

1. "永远更新 root"：非根实例委托给根

方法开头先取this[ROOT]，如果当前实例不是根，直接return root.update()委托出去。这与setProps()、setState()、unmount()等方法的守卫模式一致（均抛出can only be called on the root错误），区别在于update()选择的是静默委托而非报错。

2. "只更新 Enzyme 的表示"：privateSetNodes

真正干活的是一行：

privateSetNodes(this, this[RENDERER].getNode());

this[RENDERER].getNode()是从适配器（adapter）的渲染器上重新取一次当前已渲染的组件树，然后 privateSetNodes 把它写入 wrapper 私有的NODE/NODES字段并同步length。整个过程中没有任何render()调用——这就是"不强制重渲染"的源码证据：它只做读取 + 覆盖缓存，React 侧一个字节都不会变。

3. 关联根同步：wrappingComponent场景

当通过mount(..., { wrappingComponent })挂载时，构造函数会创建一个特殊的WrappingComponentWrapper（ReactWrapper.js）并与主根互相推入对方的LINKED_ROOTS。update()遍历这些关联根并递归同步，保证主 wrapper 和 wrapping wrapper 两侧的快照一致（测试用例可见 getWrappingComponent.jsx）。

其中UPDATED_BY哨兵（配合try/finally还原）是一个精妙的递归保护：两个根互为关联根时，A 更新 B、B 又更新 A 会形成无限循环。源码注释明确写道——"Only update a linked it root if it is not the originator of our update(). This is needed to prevent infinite recursion when there is a bi-directional link between two roots."

与其他 API 的分工：谁会"自己更新"，谁需要你手动调用

从源码看，Enzyme 内部所有会真正触发 React 重渲染的方法，都会在渲染回调里自动调用this.update()：

• setProps()：this[RENDERER].render(this[UNRENDERED], null, () => { this.update(); ... })（L342-L358）
• setState()：在instance.setState的回调中this.update()（L373-L393）
• setContext()：渲染回调中() => this.update()（L404-L413）
• mount()/unmount()：同样在渲染/卸载后自动update()（L302-L326）

因此，只要你走的是 Enzyme 自己的 API 改状态，通常不需要再手动update()。需要手动调用的正是文档所说"something external may be updating the state"的情形，仓库测试套件里有大量真实用例可参考：

异步setState场景（ReactWrapper-spec.jsx）：

it('has updated output after an asynchronous setState', () => { const wrapper = mount(<Test />); wrapper.find('.async-btn').simulate('click'); return new Promise((resolve) => { setImmediate(() => { wrapper.update(); // 异步状态落地后，手动对齐快照 resolve(); }); }).then(() => { expect(wrapper.find('.show-me')).to.have.lengthOf(1); }); });

子组件通过 props 回调改父状态（ReactWrapper-spec.jsx）：

it('has updated output after child prop callback invokes setState', () => { const wrapper = mount(<Test />); wrapper.find(Child).props().callback(); wrapper.update(); expect(wrapper.find('.show-me')).to.have.lengthOf(1); });

Hooks 场景：在useState/useEffect/useReducer等 Hook 测试（如 useState.jsx）中，事件模拟后触发 Hook 状态更新时，同样依赖wrapper.update()刷新快照后再断言。

与 ShallowWrapper 的update()的差异

shallow()渲染的ShallowWrapper也有update()（ShallowWrapper.js），但约束更严格：

if (this[ROOT] !== this) { throw new Error('ShallowWrapper::update() can only be called on the root'); } if (this[NODES].length !== 1) { throw new Error('ShallowWrapper::update() can only be called when wrapping one node'); }

即 ShallowWrapper 的update()必须在根上调用，且只能包装单个节点；而 ReactWrapper 版本对子实例采取静默委托到根的宽松策略。这是两者在错误处理哲学上的一个显著区别。

实战要点小结

• 判断是否需要update()的标准：状态变化是否绕过了 Enzyme 的 API（异步 setState、外部回调、instance()方法调用、setImmediate/Promise 中的更新）；
• update()是纯快照操作，成本很低，在不确定时"先 update 再断言"是安全习惯；
• 需要真正强制重渲染时，请用wrapper.setProps({})，不要用update()替代；
• 在wrappingComponent挂载时，update()会自动同步主根与 wrapping wrapper 两侧的快照，无需分别调用。

【免费下载链接】enzymeJavaScript Testing utilities for React项目地址: https://gitcode.com/gh_mirrors/en/enzyme