enzyme ShallowWrapper.instance() 详解：获取 React 组件实例的正确姿势

enzyme ShallowWrapper.instance() 详解：获取 React 组件实例的正确姿势

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

本篇指南聚焦 enzyme 中ShallowWrapper.instance()方法，讲解如何在浅渲染（shallow rendering）场景下取得被测试组件底层真实的类实例、为何它在函数组件（SFC）上会返回null，以及调用它的两条硬性前提（单节点 + 根实例）。读完你不仅能正确写出wrapper.instance()的测试断言，还能理解其内部实现与state()、setState()、context()等方法的关联，避免踩中"只能在 root 上调用"这类常见报错。

方法签名与返回值

instance() => ReactComponent | DOMComponent

instance()返回单节点 wrapper 所包裹节点对应的底层类实例，也就是组件方法中this指向的那个对象。通过它可以绕过 React 渲染层，直接访问组件实例上的自定义方法、原生属性等。它的使用对象是"包裹单个节点的 wrapper"——如果 wrapper 同时包裹多个节点，该方法无法正常工作（详见下文错误处理一节）。

从 packages/enzyme/src/ShallowWrapper.js 的源码可以看到其完整实现：

instance() { if (this[ROOT] !== this) { throw new Error('ShallowWrapper::instance() can only be called on the root'); } return this[RENDERER].getNode().instance; }

实现只有两步：先校验当前 wrapper 是否为 root，然后从渲染器（renderer）维护的节点树中取出.instance字段返回。这说明instance()本质上是浅渲染内部节点树上一个已挂载好的实例引用，而非重新实例化得到的新对象。

两条硬性前提：单节点 + 根实例

前提一：只能作用于单节点 wrapper

官方文档明确说明instance()必须作用于单节点 wrapper（"It must be a single-node wrapper"）。共享测试套件 packages/enzyme-test-suite/test/shared/methods/instance.jsx 中专门验证了多节点场景（该用例仅对非 shallow 的 wrapper 生效，因为 ShallowWrapper 本身还会触发根实例校验）：

const wrapper = Wrap(<Test />).find('span'); // 匹配到两个 <span> expect(() => wrapper.instance()).to.throw( Error, 'Method "instance" is meant to be run on 1 node. 2 found instead.', );

当 wrapper 包裹多个节点时，无法确定"到底返回哪一个实例"，因此直接抛错。

前提二：只能在 root wrapper 上调用

文档强调："can only be called on a wrapper instance that is also the root instance"。也就是说，通过find()、findWhere()、children()等派生出来的非根 wrapper不能调用instance()。测试套件 instance.jsx 验证了这一点：

const wrapper = Wrap(<Foo />); const div = wrapper.find('div'); expect(() => div.instance()).to.throw( Error, 'ShallowWrapper::instance() can only be called on the root', );

这与源码中if (this[ROOT] !== this)的守卫一一对应。其背后的设计逻辑是：浅渲染时渲染器（renderer）只完整挂载了根组件，子节点的类实例信息并不保证始终可用，因此把能力严格限制在 root 上。

React 16+ 与 15.x：函数组件实例的版本差异

这是instance()最重要的行为差异，文档单独用两个小节说明：

React 16 及以上：SFC 返回null

function SFC() { return <div>MyFunction</div>; } class Stateful extends React.Component { render() { return <div>MyClass</div>; } } test('wrapper instance is null', () => { const wrapper = shallow(<SFC />); const instance = wrapper.instance(); expect(instance).to.equal(null); }); test('wrapper instance is not null', () => { const wrapper = shallow(<Stateful />); const instance = wrapper.instance(); expect(instance).to.be.instanceOf(Stateful); });

从 React 16 开始，函数组件不再拥有类实例，因此instance()对 SFC 一律返回null——无论组件内部是否使用了 Hooks（useState、useEffect等都不会改变这一结果）。这由 React 16 的 Fiber 架构决定：函数组件节点上不存在this，也没有可供 enzyme 提取的实例对象。测试套件 instance.jsx 也断言了这一点：

itIf(is('>= 16'), 'has no instance', () => { const wrapper = Wrap(<SFC />); expect(wrapper.instance()).to.equal(null); });

React 15.x：SFC 也有"实例"

test('wrapper instance is not null', () => { const wrapper = shallow(<SFC />); const instance = wrapper.instance(); expect(instance).to.be.instanceOf(SFC); }); test('wrapper instance is not null', () => { const wrapper = shallow(<Stateful />); const instance = wrapper.instance(); expect(instance).to.be.instanceOf(Stateful); });

在 React 15 及更早版本中，函数组件同样会被创建为可实例化的组件对象，因此wrapper.instance()返回的是该函数组件自身的实例（instanceof SFC为真）。测试套件中对应分支是：

itIf(is('< 16'), 'has an instance', () => { const wrapper = Wrap(<SFC />); expect(wrapper.instance()).not.to.equal(null); });

建议：如果你的测试需要兼容多个 React 大版本，请务必针对 SFC 的返回值分版本编写断言，不要假设"总是有实例"或"总是 null"。

返回实例能做什么

instance()返回的对象就是组件内部this所指向的实例，因此可以：

• 直接调用组件实例上的自定义方法，例如wrapper.instance().myMethod()；
• 断言实例类型，例如expect(wrapper.instance()).to.be.instanceOf(Stateful)；
• 校验方法是否来自原型，测试套件中就有expect(wrapper.instance().render).to.equal(Foo.prototype.render)的写法；
• 访问实例上的字段与内部状态。

一个常见误区是拿它和getElement()混淆：getElement()返回的是 React 元素（描述渲染结构的对象），而instance()返回的是真实挂载的组件实例。在 ShallowWrapper 中，旧的getNode()已被废弃，源码 ShallowWrapper.js 明确提示改用getElement()，而获取实例的唯一入口就是instance()。

内部联动：instance() 是 state/context 等方法的基石

instance()不仅是公开 API，也是 ShallowWrapper 内部多个方法的基础设施。在 packages/enzyme/src/ShallowWrapper.js 和 L1190 附近可以看到，state()、setState()、context()等方法都通过this.instance()取得实例，再用nodeType !== 'class'判断节点是否为类组件，例如：

if (this.instance() === null || this[RENDERER].getNode().nodeType !== 'class') { // 针对非类组件抛错或降级处理 }

这解释了为什么在 React 16+ 中，对 SFC 调用wrapper.state()等依赖实例的方法会失败——因为instance()已经返回null。理解这条调用链，有助于排查"为什么对函数组件取不到 state/context"的报错。

与其他 Wrapper 类型对比

instance()并非 ShallowWrapper 独有，但行为细节略有不同：

// ReactWrapper 中的实现：没有 ROOT 守卫，但要求单节点 instance() { return this.single('instance', () => this[NODE].instance); }

如果你的测试需要"在查找出的子节点上取实例"，应当考虑使用mount()+ReactWrapper.instance()，而不是shallow()。

小结

• wrapper.instance()返回浅渲染根组件的真实类实例（ReactComponent | DOMComponent）；
• 必须满足单节点与根实例两个前提，否则抛错；
• React 16+ 中函数组件无论是否使用 Hooks，instance()一律返回null；React 15.x 中则返回函数组件实例；
• 类组件可用instance()调用自定义方法、断言类型、验证原型方法；
• state()、setState()、context()等内部依赖instance()，SFC 上这些方法同样受限；
• 需要子节点实例时请改用mount()+ReactWrapper.instance()。

相关参考：方法源码见 packages/enzyme/src/ShallowWrapper.js，共享测试见 packages/enzyme-test-suite/test/shared/methods/instance.jsx，shallow()的完整用法见 docs/api/shallow.md。

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