{"id":11852,"library":"react-select-event","title":"React Select Event Simulation","description":"react-select-event is a specialized companion library for React Testing Library, designed to accurately simulate user interactions on `react-select` components in unit and integration tests. The current stable version is `5.5.1`. This library has an active release cadence, with frequent minor and patch updates, alongside occasional major versions introducing significant features or breaking changes. Its key differentiators include its tight integration with `react-testing-library`'s ecosystem, enabling robust testing of complex `react-select` scenarios like asynchronous option loading, multi-select, and portal-rendered menus. It automatically wraps actions in React's `act` utility (since v5.1.0) to prevent common `act` warnings, and supports `react-select` versions from 2.1.0 onwards. It streamlines testing workflows by providing high-level event simulation functions that mimic real user behavior, unlike lower-level `fireEvent` calls that might not fully replicate `react-select`'s internal state management.","status":"active","version":"5.5.1","language":"javascript","source_language":"en","source_url":"https://github.com/romgain/react-select-event","tags":["javascript","react-testing-library","dom-testing-library","react-select","testing","unit-testing","typescript"],"install":[{"cmd":"npm install react-select-event","lang":"bash","label":"npm"},{"cmd":"yarn add react-select-event","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-select-event","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This library is designed to interact with `react-select` components. It is not a direct runtime dependency but is implicitly required in the project where `react-select-event` is used for testing.","package":"react-select","optional":true},{"reason":"This library extends `@testing-library/react` for simulating events. It is a testing helper that operates within the `react-testing-library` environment.","package":"@testing-library/react","optional":true},{"reason":"The library depends on React for its testing utilities and component rendering context. Explicitly listing for clarity.","package":"react","optional":true}],"imports":[{"note":"The library primarily exports a default object named `selectEvent` which contains all the helper functions like `select`, `create`, `clearAll`, etc. Attempting named imports for the helper functions directly from the package will fail.","wrong":"import { selectEvent } from 'react-select-event';\n// Or incorrect direct import:\nimport { select } from 'react-select-event';","symbol":"selectEvent","correct":"import selectEvent from 'react-select-event';"},{"wrong":"import { select } from 'react-select-event';\n// `select` is a method on the `selectEvent` default export, not a top-level named export.","symbol":"select","correct":"import selectEvent from 'react-select-event';\nawait selectEvent.select(inputElement, 'Option Label');"},{"wrong":"import { create } from 'react-select-event';\n// `create` is a method on the `selectEvent` default export.","symbol":"create","correct":"import selectEvent from 'react-select-event';\nawait selectEvent.create(inputElement, 'New Option');"}],"quickstart":{"code":"import React from 'react';\nimport Select from 'react-select';\nimport { render, screen, fireEvent } from '@testing-library/react';\nimport selectEvent from 'react-select-event';\n\nconst OPTIONS = [\n  { value: 'chocolate', label: 'Chocolate' },\n  { value: 'strawberry', label: 'Strawberry' },\n  { value: 'vanilla', label: 'Vanilla' },\n  { value: 'mango', label: 'Mango' },\n];\n\nconst MyForm = ({ isMulti = false, menuPortalTarget = undefined }) => (\n  <form data-testid=\"form\">\n    <label htmlFor=\"food\">Favorite Food</label>\n    <Select\n      options={OPTIONS}\n      name=\"food\"\n      inputId=\"food\"\n      isMulti={isMulti}\n      menuPortalTarget={menuPortalTarget}\n    />\n  </form>\n);\n\ndescribe('react-select-event basic usage', () => {\n  it('should select a single option', async () => {\n    render(<MyForm />);\n    expect(screen.getByTestId('form')).toHaveFormValues({ food: '' });\n\n    await selectEvent.select(screen.getByLabelText('Favorite Food'), 'Vanilla');\n\n    expect(screen.getByTestId('form')).toHaveFormValues({ food: 'vanilla' });\n  });\n\n  it('should select multiple options when isMulti is true', async () => {\n    render(<MyForm isMulti />);\n    expect(screen.getByTestId('form')).toHaveFormValues({ food: [] });\n\n    await selectEvent.select(screen.getByLabelText('Favorite Food'), ['Strawberry', 'Mango']);\n\n    expect(screen.getByTestId('form')).toHaveFormValues({ food: ['strawberry', 'mango'] });\n  });\n\n  it('should handle async select options by typing', async () => {\n    const loadOptions = (inputValue: string) =>\n      Promise.resolve(\n        OPTIONS.filter(option => option.label.toLowerCase().includes(inputValue.toLowerCase()))\n      );\n    // A minimal Async component for demonstration\n    const AsyncSelect = (props: any) => (\n      <Select {...props} loadOptions={loadOptions} cacheOptions defaultOptions />\n    );\n\n    render(\n      <form data-testid=\"async-form\">\n        <label htmlFor=\"async-food\">Async Food</label>\n        <AsyncSelect name=\"async-food\" inputId=\"async-food\" />\n      </form>\n    );\n    expect(screen.getByTestId('async-form')).toHaveFormValues({ 'async-food': '' });\n\n    // Simulate typing to trigger loadOptions\n    fireEvent.change(screen.getByLabelText('Async Food'), { target: { value: 'choco' } });\n    await selectEvent.select(screen.getByLabelText('Async Food'), 'Chocolate');\n\n    expect(screen.getByTestId('async-form')).toHaveFormValues({ 'async-food': 'chocolate' });\n  });\n});","lang":"typescript","description":"Demonstrates selecting single and multiple options in a `react-select` component, including handling async selects, and verifying form values using `react-testing-library`."},"warnings":[{"fix":"If you were using `autoSelect: true` with `selectEvent.create`, remove it and use `waitForElement: true` in the configuration object instead. For example, `selectEvent.create(input, 'New Option', { waitForElement: true })`.","message":"The `autoSelect` option, introduced in `v4.2.0` for the `create` function, was removed in `v5.0.0`. It has been replaced by the `waitForElement` option, providing more explicit control over the option creation lifecycle. This change primarily impacts users who upgraded from `v4.2.0` to `v5.0.0` or newer.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Upgrade `react-select-event` to `v5.5.1` or a newer version to ensure full compatibility and correct behavior with React 18 and `@testing-library/react` v13.","message":"`react-select-event` versions prior to `v5.5.1` might encounter compatibility issues, specifically `select` not working as expected, when used with React 18 and `@testing-library/react` v13. This was addressed in `v5.5.1`.","severity":"gotcha","affected_versions":"<5.5.1"},{"fix":"Always pass the portal target element to the `config.container` option of `selectEvent.select`. For example, `await selectEvent.select(input, 'Option', { container: document.body })`. If the container needs lazy evaluation, it can also be a function.","message":"When `react-select` renders its dropdown menu into a portal (e.g., using `menuPortalTarget={document.body}`), `react-select-event` might fail to locate and interact with the options. This results in selection failures or elements not found errors if the `container` option is not explicitly provided.","severity":"gotcha","affected_versions":">=2.1.0 (react-select's feature)"},{"fix":"Upgrade to `react-select-event` `v5.1.0` or newer, as all internal actions are automatically wrapped in `act` since this version. If upgrading is not possible, manually wrap `selectEvent` calls in `await act(async () => { await selectEvent.select(...) })`.","message":"Prior to `v5.1.0`, interactions with `react-select-event` might sometimes lead to 'An update to [...] inside a test was not wrapped in act(...)' warnings from React Testing Library. This occurs when state updates happen outside of React's `act` utility calls.","severity":"gotcha","affected_versions":"<5.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the text passed to `selectEvent.select` precisely matches the visible label of an option. If `react-select` loads options asynchronously (e.g., `AsyncSelect`), make sure to simulate typing into the input (`fireEvent.change`) to trigger option loading before attempting to select. Also, confirm the `container` config is set correctly if `menuPortalTarget` is used.","cause":"The option text provided to `selectEvent.select` does not match any currently available or rendered options in the dropdown, or the dropdown menu itself is not open/visible.","error":"TestingLibraryElementError: Unable to find an element with the text: [Your Option Text]"},{"fix":"Upgrade `react-select-event` to `v5.1.0` or newer. This version automatically wraps all interactions in `act` to prevent these warnings. If on an older version, manually wrap your `selectEvent.select` calls within `await act(async () => { ... })`.","cause":"React's `act` warning indicates that a state update occurred during testing that was not properly batched or awaited. This often happens with asynchronous operations in components.","error":"Warning: An update to %s inside a test was not wrapped in act(...)."},{"fix":"When using `menuPortalTarget` in your `react-select` component, provide the same target element (e.g., `document.body`) to the `config.container` option of `selectEvent.select`. Example: `await selectEvent.select(input, 'Option', { container: document.body })`.","cause":"This error typically occurs when `react-select-event` tries to find elements within the default testing container, but the `react-select` dropdown has been rendered into a different DOM node (a portal) using `menuPortalTarget`.","error":"TypeError: Cannot read properties of undefined (reading 'querySelector')"}],"ecosystem":"npm"}