{"id":14551,"library":"enzyme-adapter-utils","title":"Enzyme Adapter Utilities","description":"The `enzyme-adapter-utils` package (version 1.14.2, last published 2 years ago) serves as a foundational utility layer for developing and maintaining official and third-party Enzyme adapters. It provides common functionalities, abstract classes (like `EnzymeAdapter`), and helper methods necessary for an adapter to bridge Enzyme's API with specific versions of React or other UI component libraries (e.g., Preact, Inferno). Unlike the main `enzyme` package, `enzyme-adapter-utils` is not intended for direct use by application developers writing tests. Its primary consumers are the developers of `enzyme-adapter-react-*` packages. As an internal component of the Enzyme ecosystem, its release cadence is tightly coupled with major Enzyme releases and React compatibility updates. It enables the modularity of Enzyme, allowing it to support multiple React versions simultaneously without requiring a monolithic testing library. This package is crucial for ensuring Enzyme's continued compatibility with the evolving React landscape, although the broader Enzyme ecosystem faces challenges with newer React versions.","status":"maintenance","version":"1.14.2","language":"javascript","source_language":"en","source_url":"https://github.com/enzymejs/enzyme","tags":["javascript","shallow rendering","shallowRender","test","reactjs","react","flux","testing"],"install":[{"cmd":"npm install enzyme-adapter-utils","lang":"bash","label":"npm"},{"cmd":"yarn add enzyme-adapter-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add enzyme-adapter-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Enzyme adapters (which build upon these utilities) have peer dependencies on `react` for specific versions they support.","package":"react","optional":true},{"reason":"Used for runtime type checking of props within adapter utilities.","package":"prop-types","optional":false},{"reason":"Used for semantic version comparisons, likely for adapter compatibility checks.","package":"semver","optional":false}],"imports":[{"note":"This is the default export, representing the base class for custom Enzyme adapters. It is primarily used by developers creating Enzyme adapters, not by application developers writing tests.","wrong":"import { EnzymeAdapter } from 'enzyme-adapter-utils';","symbol":"EnzymeAdapter","correct":"import EnzymeAdapter from 'enzyme-adapter-utils';"},{"note":"A named export representing a node in Enzyme's internal React Standard Tree (RST) structure. This is used by adapter developers to build and manipulate the component trees for Enzyme's API.","wrong":"import RSTreeNode from 'enzyme-adapter-utils';","symbol":"RSTreeNode","correct":"import { RSTreeNode } from 'enzyme-adapter-utils';"},{"note":"A named utility function used internally by Enzyme adapters, typically in the context of `mount` rendering, to ensure proper synchronization with React DOM's internals for consistent behavior.","wrong":"import syncWithReactDom from 'enzyme-adapter-utils';","symbol":"syncWithReactDom","correct":"import { syncWithReactDom } from 'enzyme-adapter-utils';"}],"quickstart":{"code":"import EnzymeAdapter, { RSTreeNode, syncWithReactDom } from 'enzyme-adapter-utils';\nimport { configure } from 'enzyme';\n\n// This is an illustrative example of a custom adapter using enzyme-adapter-utils.\n// End-users typically install and configure existing adapters (e.g., enzyme-adapter-react-16).\n\nclass CustomEnzymeAdapter extends EnzymeAdapter {\n  constructor() {\n    super();\n    console.log('CustomEnzymeAdapter initialized.');\n  }\n\n  // Required methods for a custom adapter (simplified for example):\n  createRenderer(options) {\n    if (options.mode === 'mount') {\n      syncWithReactDom(); // Example utility usage\n    }\n    console.log(`Creating renderer for mode: ${options.mode}`);\n    return {\n      render: (node, context) => {\n        // In a real adapter, this would perform actual rendering\n        console.log('Rendering node:', node);\n        // Return a mock RSTreeNode for demonstration\n        return new RSTreeNode('div', { className: 'rendered' }, [], null);\n      },\n      unmount: (node) => console.log('Unmounting node:', node),\n      getNode: (node) => new RSTreeNode('span', {}, [], null), // Example utility usage\n    };\n  }\n\n  // Other required adapter methods would be implemented here\n  isValidElement(element) { return true; }\n  nodeToElement(node) { return node; }\n  nodeToHostNode(node) { return null; }\n  displayNameOfNode(node) { return node.type || 'Unknown'; }\n  // ... many more methods\n}\n\n// To actually use this adapter, you would configure Enzyme with it:\n// configure({ adapter: new CustomEnzymeAdapter() });\n\nconsole.log('This code demonstrates how a custom Enzyme adapter would leverage `enzyme-adapter-utils`.');\nconsole.log('The EnzymeAdapter class, RSTreeNode, and syncWithReactDom are internal utilities for adapter authors.');\nconsole.log('Direct usage by typical test authors is uncommon and not recommended.');","lang":"typescript","description":"This quickstart demonstrates how a custom Enzyme adapter, designed by a library developer, would extend `EnzymeAdapter` and utilize internal utilities like `RSTreeNode` and `syncWithReactDom` from `enzyme-adapter-utils`. It is not for end-users writing tests."},"warnings":[{"fix":"Refer to the Enzyme migration guide from v2 to v3. Ensure you are using `enzyme` v3.x and an `enzyme-adapter-react-*` package compatible with your React version (e.g., `enzyme-adapter-react-16` for React 16).","message":"Enzyme's major version 3 introduced an adapter system, which fundamentally changed how Enzyme interacts with React versions. This involved significant refactors in internal utility packages like `enzyme-adapter-utils`. Older adapters (v2.x) are incompatible with Enzyme v3.x and require migration.","severity":"breaking","affected_versions":"<3.0.0"},{"fix":"For React 17+ (especially React 18+), it is highly recommended to migrate from Enzyme to React Testing Library, which is officially supported by the React team and focuses on user-centric testing.","message":"Enzyme, and by extension its adapter utilities, has faced significant challenges maintaining compatibility with newer React versions (17, 18, and beyond) due to reliance on React's private internal APIs. There is no official Enzyme adapter for React 18, and the library is largely unmaintained, with its ecosystem frozen. This means `enzyme-adapter-utils` is unlikely to receive updates for future React API changes.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Application developers should only interact with the public API of the main `enzyme` package and a specific `enzyme-adapter-react-*` package. Custom adapter development is a niche use case.","message":"`enzyme-adapter-utils` is an internal package used by adapter developers, not directly by application developers. Attempting to import and use its functions or classes directly in application test code is usually an anti-pattern and can lead to unstable tests or unexpected behavior due to internal API changes.","severity":"gotcha","affected_versions":"*"},{"fix":"Wrap any code that triggers state updates or effects outside of Enzyme's automatic `act` wrapping with `ReactTestUtils.act(() => { /* ... */ });` or similar `act` utilities relevant to your React version and testing setup.","message":"When using `mount` with React 16.8+ (which introduced Hooks and `act()`), Enzyme automatically wraps relevant APIs (like `.simulate()`, `.setProps()`) with `ReactTestUtils.act()`. However, for other state updates or effects triggered outside these specific APIs, you might need to manually wrap them with `act` (e.g., from `react-test-renderer/test-utils` or `@testing-library/react`) to ensure consistent test behavior and prevent 'act' warnings.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the correct `enzyme-adapter-react-*` package for your React version (e.g., `npm i --save-dev enzyme-adapter-react-16`) and configure Enzyme in your test setup file: `import Enzyme from 'enzyme'; import Adapter from 'enzyme-adapter-react-16'; Enzyme.configure({ adapter: new Adapter() });`","cause":"The Enzyme library has not been configured with a specific adapter for your React version.","error":"Enzyme Internal Error: Enzyme expects an adapter to be configured, but found none."},{"fix":"Ensure that your `react` and `react-dom` versions are compatible with the specific `enzyme-adapter-react-*` package you are using. If conflicts persist, try `npm install --force` or `npm install --legacy-peer-deps` (use with caution as it can lead to broken dependencies) or downgrade/upgrade React to match the adapter's requirements.","cause":"Dependency conflicts, often between your project's React version and the `peerDependencies` of `enzyme-adapter-react-*` or `enzyme-adapter-utils` packages. This is common when upgrading React without updating Enzyme adapters, or with incompatible versions.","error":"npm ERR! code ERESOLVE npm ERR! ERESOLVE unable to resolve dependency tree"},{"fix":"Verify that your custom adapter correctly extends `EnzymeAdapter` or reinstall the official `enzyme-adapter-react-*` package to ensure it's not corrupted. Ensure no conflicting versions of `enzyme-adapter-utils` are present.","cause":"The adapter provided to `Enzyme.configure()` does not correctly extend the `EnzymeAdapter` class from `enzyme-adapter-utils` or is otherwise malformed. This error is typically encountered when developing a custom adapter or if an existing adapter package is corrupted/incorrect.","error":"Enzyme Internal Error: configured enzyme adapter did not inherit from the EnzymeAdapter base class"}],"ecosystem":"npm"}