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 | DOMComponentinstance()返回单节点 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()必须作用于单节点 wrapperIt 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 返回nullfunction SFC() { return divMyFunction/div; } class Stateful extends React.Component { render() { return divMyClass/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——无论组件内部是否使用了 HooksuseState、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.xSFC 也有实例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 独有但行为细节略有不同Wrapper 类型对应文档差异要点ShallowWrapper.instance()本文只能在 root 上调用多节点直接抛错React 16 对 SFC 返回nullReactWrapper.instance()docs/api/ReactWrapper/instance.md通过single(instance, ...)保证单节点见 ReactWrapper.js可在非根节点上使用mount()场景下约束更宽松// ReactWrapper 中的实现没有 ROOT 守卫但要求单节点 instance() { return this.single(instance, () this[NODE].instance); }如果你的测试需要在查找出的子节点上取实例应当考虑使用mount()ReactWrapper.instance()而不是shallow()。小结wrapper.instance()返回浅渲染根组件的真实类实例ReactComponent | DOMComponent必须满足单节点与根实例两个前提否则抛错React 16 中函数组件无论是否使用 Hooksinstance()一律返回nullReact 15.x 中则返回函数组件实例类组件可用instance()调用自定义方法、断言类型、验证原型方法state()、setState()、context()等内部依赖instance()SFC 上这些方法同样受限需要子节点实例时请改用mount()ReactWrapper.instance()。相关参考方法源码见 packages/enzyme/src/ShallowWrapper.js共享测试见 packages/enzyme-test-suite/test/shared/methods/instance.jsxshallow()的完整用法见 docs/api/shallow.md。【免费下载链接】enzymeJavaScript Testing utilities for React项目地址: https://gitcode.com/gh_mirrors/en/enzyme创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考