{"id":13559636,"url":"https://github.com/preactjs/enzyme-adapter-preact-pure","last_synced_at":"2025-04-09T16:20:59.091Z","repository":{"id":38416858,"uuid":"169861138","full_name":"preactjs/enzyme-adapter-preact-pure","owner":"preactjs","description":"Preact adapter for the Enzyme UI testing library","archived":false,"fork":false,"pushed_at":"2023-05-01T04:59:44.000Z","size":2182,"stargazers_count":67,"open_issues_count":19,"forks_count":17,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-10-29T15:32:34.426Z","etag":null,"topics":["enzyme","preact","testing"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/preactjs.png","metadata":{"funding":{"github":["preactjs"],"open_collective":"preact"},"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2019-02-09T11:42:34.000Z","updated_at":"2024-09-03T02:41:19.000Z","dependencies_parsed_at":"2023-09-24T05:12:02.225Z","dependency_job_id":"97483440-170f-4a61-978b-5af93d42dc75","html_url":"https://github.com/preactjs/enzyme-adapter-preact-pure","commit_stats":{"total_commits":377,"total_committers":15,"mean_commits":"25.133333333333333","dds":0.4137931034482759,"last_synced_commit":"65d479e1fbd4cbdeea1e4bef3de5b512aa221002"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preactjs%2Fenzyme-adapter-preact-pure","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preactjs%2Fenzyme-adapter-preact-pure/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preactjs%2Fenzyme-adapter-preact-pure/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preactjs%2Fenzyme-adapter-preact-pure/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/preactjs","download_url":"https://codeload.github.com/preactjs/enzyme-adapter-preact-pure/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247338481,"owners_count":20922985,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["enzyme","preact","testing"],"created_at":"2024-08-01T13:00:30.283Z","updated_at":"2025-04-09T16:20:59.048Z","avatar_url":"https://github.com/preactjs.png","language":"TypeScript","funding_links":["https://github.com/sponsors/preactjs","https://opencollective.com/preact"],"categories":["CLI Commands"],"sub_categories":[],"readme":"# enzyme-adapter-preact-pure\n\nThis is an adapter to support using the [Enzyme](https://enzymejs.github.io/enzyme/) UI\ncomponent testing library with [Preact](https://preactjs.com). For documentation, please see [the testing guide on the PreactJS website](https://preactjs.com/guide/v10/unit-testing-with-enzyme).\n\n## Supported Preact versions\n\nVersion 3.x of the adapter supports Preact v10+. Earlier versions support both\nPreact v8 and v10.\n\n## Usage\n\nAdd the library to your development dependencies:\n\n```sh\n# If using npm\nnpm install --save-dev enzyme-adapter-preact-pure\n\n# If using yarn\nyarn add --dev enzyme-adapter-preact-pure\n```\n\nThen in the setup code for your tests, configure Enzyme to use the adapter\nprovided by this package:\n\n```js\nimport { configure } from 'enzyme';\nimport Adapter from 'enzyme-adapter-preact-pure';\n\nconfigure({ adapter: new Adapter() });\n```\n\nOnce the adapter is configured, you can write Enzyme tests for your Preact\nUI components following the [Enzyme docs](https://enzymejs.github.io/enzyme/).\nThe full DOM rendering, shallow rendering and string rendering modes are\nsupported.\n\n## Example projects\n\nFor runnable example projects, see the [examples/](examples/) directory. To run the\nexamples locally, clone this repository, then run:\n\n```sh\ncd examples/\u003cproject name\u003e\nnpm install\nnpm test\n```\n\n## Differences compared to Enzyme + React\n\nThe general intent is that tests written using Enzyme + React can be easily made\nto work with Enzyme + Preact or vice-versa. However there are some differences\nin behavior between this adapter and Enzyme's React adapters to be aware of:\n\n### Shallow rendering\n\n- When using Enzyme's shallow rendering mode, this adapter _always_ invokes the\n  component's lifecycle methods (`componentDidUpdate` etc.).\n  The `disableLifecycleMethods` option is not respected.\n\n- React's shallow rendering does not create actual DOM nodes. The shallow\n  rendering implemented by this adapter does. It works by simply by rendering\n  the component as normal, except making any child components output only the\n  children passed to them. In other words, during shallow rendering, all child\n  components behave as if they were defined like this:\n\n  ```js\n  function ShallowRenderedChild({ children }) {\n    return children;\n  }\n  ```\n\n  This means that any side effects that rendered DOM elements have, such as `\u003cimg\u003e`\n  elements loading images, will still execute.\n\nIf you are converting a React Enzyme test suite to use Preact, try out our `CompatShallowRenderer`. This renderer is an alternate shallow renderer to the default that uses a custom diffing algorithm that mirrors the Preact diff algorithm but only shallowly renders elements, similarly to what [`react-shallow-render`](https://github.com/enzymejs/react-shallow-renderer) does for React components. This renderer has a couple of behaviors that more closely resembles the React adapters, including:\n\n- No DOM nodes are created, so a DOM environment is not required\n- `disableLifecycleMethods` option is respected\n- Virtual element props are preserved intact so filter methods on the Enzyme wrapper behave more similarly to the React wrappers\n\nTo enable the `CompatShallowRenderer`, pass it into the `shallowRenderer` Adapter option when configuring Enzyme:\n\n```js\nimport { configure } from 'enzyme';\nimport Adapter from 'enzyme-adapter-preact-pure';\nimport { CompatShallowRenderer } from 'enzyme-adapter-preact-pure/compat';\n\n// Setup Enzyme\nconfigure({\n  adapter: new Adapter({\n    ShallowRenderer: CompatShallowRenderer,\n  }),\n});\n```\n\n### Simulating events\n\nThe [simulate](https://enzymejs.github.io/enzyme/docs/api/ReactWrapper/simulate.html)\nAPI does not dispatch actual DOM events in the React adapters, it just calls\nthe corresponding handler. The Preact adapter does dispatch an actual event\nusing `element.dispatchEvent(...)`. Because this behavior, the Preact adapters can only simulate events on real DOM nodes, not Components.\n\nIf you'd like to simulate events on Components, enable the `simulateEventsOnComponents` option in the Adapter options. This option changes the previous behavior of how events were dispatched (by directly invoking event handlers instead of dispatching an event) and so is disabled by default. Enabling this option is useful if you are migrating an Enzyme test suite from React to Preact.\n\n```js\nimport { configure } from 'enzyme';\nimport Adapter from 'enzyme-adapter-preact-pure';\n\n// Setup Enzyme\nconfigure({\n  adapter: new Adapter({\n    simulateEventsOnComponents: true,\n  }),\n});\n```\n\n### String rendering\n\nBy default, the Preact string renderer renders your component into the DOM and then returns the `innerHTML` of the DOM container. This behavior means string rendering requires a DOM environment.\n\nIf you'd like to run tests that use the string renderer in a test environment that does not have a DOM, pass `preact-render-to-string` into the `renderToString` Adapter option. Enabling this option is useful if you are migrating an Enzyme test suite from React to Preact.\n\n```js\nimport { configure } from 'enzyme';\nimport Adapter from 'enzyme-adapter-preact-pure';\nimport renderToString from 'preact-render-to-string';\n\n// Setup Enzyme\nconfigure({\n  adapter: new Adapter({\n    renderToString,\n  }),\n});\n```\n\n### State updates\n\n`setState` synchronously re-renders the component in React, [except in event\nhandlers](https://reactjs.org/docs/faq-state.html#when-is-setstate-asynchronous).\nPreact on the other hand by default batches together calls to `setState` within\nthe same tick of the event loop and schedules a render to happen in a future\nmicrotask. React's behavior [may change in a future release](https://stackoverflow.com/a/48610973/434243).\n\nTo make writing tests easier, the Preact adapter will apply any pending state\nupdates and re-render when:\n\n- The component is initially rendered by `mount` or `shallow`\n- An Enzyme API call is made that is expected to trigger a change in the\n  rendered output, such as `wrapper.setProps`, `wrapper.simulate` or\n  `wrapper.setState`\n- `wrapper.update` is called explicitly by a test\n\nThe consequences of this when writing tests are that any state updates triggered\noutside of an Enzyme method call will not be reflected in the rendered DOM until\n`wrapper.update` is called. Note this function also needs to be called when using\nReact, as it synchronizes Enzyme's snapshot of the output with the actual DOM\ntree.\n\n**Example:**\n\n```js\nconst wrapper = shallow(\u003cParentComponent /\u003e);\n\n// Trigger a state update outsize of Enzyme.\nwrapper.find(ChildComponent).props().onClick();\n\n// Update the Enzyme wrapper's snapshot.\nwrapper.update();\n\n// Test that parent component updated as expected.\n```\n\nWhen using the [Hooks](https://reactjs.org/docs/hooks-intro.html) API you also\nneed to wrap any code which triggers effects in an\n[act](https://reactjs.org/docs/test-utils.html#act) call in order to flush\neffects and trigger a re-render. The initial render and calls to APIs such as\n`setProps` or `simulate` are automatically wrapped in `act` for you.\n\nIn Preact the `act` function is available in the \"preact/test-utils\" package.\n\n```js\nimport { act } from 'preact/test-utils';\n\n// Any effects scheduled by the initial render will run before `mount` returns.\nconst wrapper = mount(\u003cWidget showInputField={false} /\u003e);\n\n// Perform an action outside of Enzyme which triggers effects in the parent\n// `Widget`. Since Enzyme doesn't know about this, we have to wrap the calls\n// with `act` to make effects execute before we call `wrapper.update`.\nact(() =\u003e {\n  wrapper.find(ChildWidget).props().onButtonClicked();\n});\n\n// Update the Enzyme wrapper's snapshot\nwrapper.update();\n```\n\n### Property names\n\nIn order to support Enzyme's class selectors, `class` props on Preact components\nare mapped to `className`.\n\n```js\nimport { mount } from 'enzyme';\n\nconst wrapper = mount(\u003cdiv class=\"widget\" /\u003e);\nwrapper.props(); // Returns `{ children: [], className: 'widget' }`\nwrapper.find('.widget').length; // Returns `1`\n```\n\n### Usage with preact/compat\n\nThis package has the same interface as the official\nenzyme-adapter-react-$version packages. If you are using preact/compat, you can\nalias enzyme-adapter-react-$version to this package in the same way as\n[preact/compat](https://preactjs.com/guide/switching-to-preact).\n\n### Usage with TypeScript\n\nThis package is compatible with TypeScript and ships with type declarations.\nIn order to mix Enzymes types from `@types/enzyme` with Preact, you will need\nto include some extensions to the \"preact\" types which are provided by this\nproject.\n\nTo do that, add the following line to one of the source files or `.d.ts` files\nfor your project:\n\n```ts\n/// \u003creference types=\"enzyme-adapter-preact-pure\" /\u003e\n```\n\nSee the TypeScript example in `examples/typescript` for a runnable example.\n\n## Development\n\nAfter cloning the repository, you can build it and run tests as follows:\n\n```sh\n# Install dependencies.\nyarn install\n\n# Build the adapter library.\nyarn build\n\n# Run tests.\nyarn test\n\n# Run tests against a custom build of Preact.\nyarn test --preact-lib \u003cpath to Preact bundle\u003e\n```\n\n### Release process\n\nNew releases of this package are created using [np](https://github.com/sindresorhus/np).\n\n1. Check out the latest `master` branch\n2. Edit CHANGELOG.md to add notes for the version you are about to release.\n3. Commit the changes to CHANGELOG.md and push back to GitHub\n4. Run `np \u003csemver-type\u003e` to create the release, where `\u003csemver-type\u003e` is the\n   category of release according to Semantic Versioning, typically `minor`.\n\n## FAQ\n\n**Can I use this library to test components that use hooks?**\n\nYes. This library supports components that use the \"Hooks\" APIs available in\nPreact v10+. You may need to use the `act` function from `preact/test-utils`\nto flush effects synchronously in certain places. See the notes above about\nstate updates in tests.\n\n**Why does the package name have a \"-pure\" suffix?**\n\nThe name has a \"-pure\" suffix to distinguish it from\n[enzyme-adapter-preact](https://github.com/aweary/enzyme-adapter-preact)\npackage which indirectly depends on React. This library is a \"pure\" Preact\nadapter which does not require Preact's React compatibility add-on.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpreactjs%2Fenzyme-adapter-preact-pure","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpreactjs%2Fenzyme-adapter-preact-pure","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpreactjs%2Fenzyme-adapter-preact-pure/lists"}