resq (React Element Selector Query) is a JavaScript library designed to query React components and HTML elements within the React Virtual DOM, emulating the functionality of `querySelector` and `querySelectorAll` for native DOM elements. It provides `resq$` for selecting a single matching component and `resq$$` for selecting multiple matches, supporting advanced features like wildcard selector patterns, asynchronous waiting for React to initialize, and filtering results by component state or props. The library is currently stable at version 1.11.0 and requires React v16 or higher. Its primary use cases include automated testing, debugging, and advanced component introspection in client-side React applications. It offers a programmatic interface to the React component tree, allowing developers to access internal component data like props and state through its `RESQNode` return structure.
npm install resqVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to install `resq`, render a basic React application, and then use `resq$` and `resq$$` to select components from the rendered tree, including waiting for React to load.
Always inspect the component tree in React DevTools to confirm the precise name of the component you intend to select, especially for components wrapped by other libraries or HOCs.
Always wrap calls to `await waitToLoadReact()` in a `try...catch` block to gracefully handle scenarios where React might not load or takes longer than expected, preventing application crashes.
Ensure `resq` is used exclusively in client-side code where `window` and `document` are available. For testing in Node.js, configure a JSDOM environment to simulate a browser.
Ensure your code runs in a browser environment. If running tests in Node.js, configure a JSDOM environment (e.g., using `jest-environment-jsdom`) to provide the necessary global objects.
Increase the timeout value passed to `waitToLoadReact(timeoutInMs)` to allow more time for React to load, or ensure React is loaded on the `window` object if it's not a global dependency.
Check if `RESQNode.node` is `null` or `undefined` before attempting to access its properties. Components like React fragments or certain HOCs might not have a direct DOM node.