React Element Selector Query (RESQ)

Common errors

• ReferenceError: document is not defined

  cause Attempting to use `resq` or its utilities in a Node.js environment without a simulated browser DOM.
  fix 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.

• resq error Error: React was not found on the window object after Xms

  cause The `waitToLoadReact` function timed out because the React global object (`window.React`) was not available within the allotted time.
  fix 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.

• TypeError: Cannot read properties of null (reading 'outerHTML')

  cause Attempting to access properties like `node.outerHTML` on a `RESQNode` where `node` is `null`, indicating the component might be a fragment or not associated with a direct DOM element.
  fix 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.

Warnings

• gotcha Component name resolution can be inconsistent for higher-order components (HOCs), Styled Components, or Material-UI components. The library relies on `displayName` or function/class names, which might be obfuscated or generic. Using React DevTools is recommended to verify the exact component names for selectors.
  Fix: 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.
• gotcha The `waitToLoadReact` function can throw an error if React is not found on the `window` object within the specified timeout duration. This can lead to unhandled promise rejections if not explicitly caught.
  Fix: 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.
• gotcha resq is designed for client-side React applications running in a browser environment, as it interacts directly with the rendered React Virtual DOM and often the browser's `document` object. It is not intended for use in Node.js server-side rendering (SSR) contexts without a JSDOM-like environment.
  Fix: 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.

Install

• npm install resq npm
• yarn add resq yarn
• pnpm add resq pnpm

Imports

• resq$
  wrong:

  const resq$ = require('resq').resq$

  correct:

  import { resq$ } from 'resq'

  Used for selecting a single React component or HTML element by its name or tag. The library primarily uses ES module syntax.
• resq$$
  wrong:

  const resq$$ = require('resq').resq$$

  correct:

  import { resq$$ } from 'resq'

  Used for selecting multiple React components or HTML elements, returning an array of RESQNode objects.
• waitToLoadReact
  wrong:

  const waitToLoadReact = require('resq').waitToLoadReact

  correct:

  import { waitToLoadReact } from 'resq'

  An asynchronous utility function to wait for React to be loaded on the window object, useful for testing or dynamically loaded applications.

Quickstart

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.

import { resq$, waitToLoadReact } from 'resq';
import React from 'react';
import ReactDOM from 'react-dom';

// A simple React component for demonstration
const MyComponent = () => (
    <div data-testid="my-component">Hello from MyComponent</div>
);

// Another component
const AnotherComponent = () => (
    <p>Another one</p>
)

// The main application component
const App = () => (
    <div>
        <MyComponent />
        <AnotherComponent />
    </div>
);

// Render the application to the DOM
const rootElement = document.createElement('div');
rootElement.id = 'root';
document.body.appendChild(rootElement);
ReactDOM.render(<App />, rootElement);

async function queryComponents() {
    try {
        // Wait for React to load, then query for 'MyComponent'
        await waitToLoadReact(1000); // Wait up to 1 second

        const myComponentNode = resq$('MyComponent');
        if (myComponentNode) {
            console.log('Found MyComponent:', myComponentNode.name, myComponentNode.node.outerHTML);
            console.log('MyComponent props:', myComponentNode.props);
        } else {
            console.log('MyComponent not found after waiting.');
        }

        // Query for multiple components using a wildcard
        const allMyComponents = resq$$('My*');
        console.log('\nFound all My* components (count:', allMyComponents.length, '):');
        allMyComponents.forEach(comp => console.log('- ' + comp.name));

    } catch (error) {
        console.error('An error occurred during resq query:', error);
    }
}

queryComponents();