@pie-lib/test-utils 0.22.1 → 0.22.2-next.164

package/src/index.js

@@ -1,18 +1,139 @@
 import * as React from 'react';
-import { shallow } from 'enzyme';
+import PropTypes from 'prop-types';
+import { render } from '@testing-library/react';
+import { ThemeProvider, createTheme } from '@mui/material/styles';
 
-export function shallowChild(Component, defaultProps = {}, nestLevel) {
-  return function innerRender(props = {}) {
-    let rendered = shallow(<Component {...defaultProps} {...props} />);
+/**
+ * Default MUI theme for testing
+ */
+const defaultTheme = createTheme();
 
-    if (nestLevel) {
-      let repeat = nestLevel;
+/**
+ * Render a component with MUI ThemeProvider
+ *
+ * @param {React.ReactElement} ui - The component to render
+ * @param {Object} options - Render options
+ * @param {Object} options.theme - Custom MUI theme (optional)
+ * @param {Object} options.renderOptions - Additional options passed to RTL render
+ * @returns {Object} RTL render result
+ *
+ * @example
+ * const { getByRole } = renderWithTheme(<Button>Click me</Button>);
+ * expect(getByRole('button')).toBeInTheDocument();
+ */
+export function renderWithTheme(ui, options = {}) {
+  const { theme = defaultTheme, ...renderOptions } = options;
 
-      while (repeat--) {
-        rendered = rendered.first().shallow();
-      }
-    }
+  function Wrapper({ children }) {
+    return <ThemeProvider theme={theme}>{children}</ThemeProvider>;
+  }
+  Wrapper.propTypes = {
+    children: PropTypes.node,
+  };
+
+  return render(ui, { wrapper: Wrapper, ...renderOptions });
+}
+
+/**
+ * Render a component with multiple providers (Theme, etc.)
+ * Useful when you need to wrap components with various context providers
+ *
+ * @param {React.ReactElement} ui - The component to render
+ * @param {Object} options - Render options
+ * @param {Object} options.theme - Custom MUI theme (optional)
+ * @param {Array<React.ComponentType>} options.providers - Additional providers to wrap
+ * @param {Object} options.renderOptions - Additional options passed to RTL render
+ * @returns {Object} RTL render result
+ *
+ * @example
+ * const { getByText } = renderWithProviders(
+ *   <MyComponent />,
+ *   { providers: [ReduxProvider, RouterProvider] }
+ * );
+ */
+export function renderWithProviders(ui, options = {}) {
+  const { theme = defaultTheme, providers = [], ...renderOptions } = options;
 
-    return rendered;
+  function Wrapper({ children }) {
+    let wrapped = <ThemeProvider theme={theme}>{children}</ThemeProvider>;
+
+    // Wrap with additional providers (from innermost to outermost)
+    providers.forEach((Provider) => {
+      wrapped = <Provider>{wrapped}</Provider>;
+    });
+
+    return wrapped;
+  }
+  Wrapper.propTypes = {
+    children: PropTypes.node,
   };
+
+  return render(ui, { wrapper: Wrapper, ...renderOptions });
+}
+
+/**
+ * Create a custom theme for testing
+ * Useful for testing components with specific theme configurations
+ *
+ * @param {Object} themeOptions - MUI theme options
+ * @returns {Object} MUI theme
+ *
+ * @example
+ * const darkTheme = createTestTheme({ palette: { mode: 'dark' } });
+ * renderWithTheme(<Component />, { theme: darkTheme });
+ */
+export function createTestTheme(themeOptions = {}) {
+  return createTheme(themeOptions);
 }
+
+/**
+ * Wait for an element to be removed from the DOM
+ * Wrapper around waitForElementToBeRemoved for convenience
+ *
+ * @example
+ * await waitForRemoval(() => screen.queryByText('Loading...'));
+ */
+export { waitForElementToBeRemoved as waitForRemoval } from '@testing-library/react';
+
+/**
+ * Re-export all of @testing-library/react for convenience
+ * This allows consumers to import everything from one place
+ */
+export * from '@testing-library/react';
+
+/**
+ * Re-export userEvent as a named export for convenience
+ */
+export { default as userEvent } from '@testing-library/user-event';
+
+/**
+ * Re-export jest-dom matchers (they're automatically added in jest.setup.js,
+ * but we export them here for TypeScript support)
+ */
+export * from '@testing-library/jest-dom';
+
+/**
+ * Keyboard helpers for testing keyboard interactions
+ * Especially useful for components checking event.keyCode
+ */
+export {
+  Keys,
+  pressKey,
+  typeAndSubmit,
+  clearAndType,
+  navigateWithKeys,
+} from './keyboard';
+
+/**
+ * Web component testing utilities
+ * For testing light DOM custom elements (no Shadow DOM)
+ */
+export {
+  waitForCustomElement,
+  renderWebComponent,
+  dispatchCustomEvent,
+  waitForEvent,
+  isCustomElementDefined,
+  createCustomElement,
+} from './web-components';
+

package/src/keyboard.js

@@ -0,0 +1,126 @@
+import userEvent from '@testing-library/user-event';
+import { fireEvent } from '@testing-library/react';
+
+/**
+ * Common keyboard key codes
+ * Useful for legacy components that check event.keyCode
+ *
+ * @example
+ * pressKey(input, Keys.ENTER);
+ * pressKey(input, Keys.ESCAPE);
+ */
+export const Keys = {
+  ENTER: 13,
+  ESCAPE: 27,
+  SPACE: 32,
+  ARROW_LEFT: 37,
+  ARROW_UP: 38,
+  ARROW_RIGHT: 39,
+  ARROW_DOWN: 40,
+  TAB: 9,
+  BACKSPACE: 8,
+  DELETE: 46,
+  HOME: 36,
+  END: 35,
+  PAGE_UP: 33,
+  PAGE_DOWN: 34,
+};
+
+/**
+ * Simulate keyboard event with keyCode
+ * Useful for legacy components checking event.keyCode
+ *
+ * userEvent.type() with special keys like {Enter} doesn't work well with
+ * components that check event.keyCode. Use this helper instead.
+ *
+ * @param {HTMLElement} element - Target element
+ * @param {number} keyCode - Key code (use Keys.ENTER, Keys.ESCAPE, etc.)
+ * @param {string} type - Event type (keydown, keyup, keypress)
+ * @param {Object} options - Additional event properties
+ *
+ * @example
+ * // Press Enter on an input
+ * const input = screen.getByRole('textbox');
+ * pressKey(input, Keys.ENTER);
+ *
+ * @example
+ * // Press Escape with keyup event
+ * pressKey(dialog, Keys.ESCAPE, 'keyup');
+ *
+ * @example
+ * // Press with additional properties
+ * pressKey(input, Keys.ENTER, 'keydown', { ctrlKey: true });
+ */
+export function pressKey(element, keyCode, type = 'keydown', options = {}) {
+  const event = new KeyboardEvent(type, {
+    keyCode,
+    which: keyCode,
+    bubbles: true,
+    cancelable: true,
+    ...options,
+  });
+
+  fireEvent(element, event);
+}
+
+/**
+ * Type text and then press Enter
+ * Common pattern for form submissions
+ *
+ * @param {HTMLElement} element - Input element
+ * @param {string} text - Text to type
+ *
+ * @example
+ * const input = screen.getByRole('textbox');
+ * await typeAndSubmit(input, 'hello world');
+ * expect(onSubmit).toHaveBeenCalledWith('hello world');
+ */
+export async function typeAndSubmit(element, text) {
+  const user = userEvent.setup();
+  await user.type(element, text);
+  pressKey(element, Keys.ENTER);
+}
+
+/**
+ * Clear input and type new text
+ * Common pattern for updating form fields
+ *
+ * @param {HTMLElement} element - Input element
+ * @param {string} text - New text to type
+ *
+ * @example
+ * const input = screen.getByRole('textbox');
+ * await clearAndType(input, 'new value');
+ */
+export async function clearAndType(element, text) {
+  const user = userEvent.setup();
+  await user.clear(element);
+  await user.type(element, text);
+}
+
+/**
+ * Simulate keyboard navigation
+ * Press arrow keys to navigate through a list
+ *
+ * @param {HTMLElement} element - List or container element
+ * @param {number} steps - Number of steps to navigate (positive = down/right, negative = up/left)
+ * @param {string} direction - 'vertical' or 'horizontal'
+ *
+ * @example
+ * // Navigate down 3 items in a list
+ * navigateWithKeys(listbox, 3, 'vertical');
+ *
+ * @example
+ * // Navigate left 2 items
+ * navigateWithKeys(tabs, -2, 'horizontal');
+ */
+export function navigateWithKeys(element, steps, direction = 'vertical') {
+  const key = direction === 'vertical'
+    ? (steps > 0 ? Keys.ARROW_DOWN : Keys.ARROW_UP)
+    : (steps > 0 ? Keys.ARROW_RIGHT : Keys.ARROW_LEFT);
+
+  const count = Math.abs(steps);
+  for (let i = 0; i < count; i++) {
+    pressKey(element, key);
+  }
+}

package/src/web-components.js

@@ -0,0 +1,200 @@
+// Note: These helpers are for light DOM web components (no Shadow DOM)
+// Standard React Testing Library queries work directly on these components
+
+/**
+ * Wait for a custom element to be defined
+ * Custom elements are registered asynchronously
+ *
+ * @param {string} tagName - Custom element tag name (e.g., 'my-component')
+ * @param {number} timeout - Timeout in milliseconds
+ * @returns {Promise<void>}
+ *
+ * @example
+ * await waitForCustomElement('pie-chart');
+ * const chart = document.createElement('pie-chart');
+ *
+ * @example
+ * await waitForCustomElement('my-component', 5000);
+ */
+export async function waitForCustomElement(tagName, timeout = 3000) {
+  if (customElements.get(tagName)) {
+    return;
+  }
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(
+        new Error(
+          `Custom element '${tagName}' not defined within ${timeout}ms. ` +
+          'Make sure the element is registered with customElements.define().'
+        )
+      );
+    }, timeout);
+
+    customElements.whenDefined(tagName).then(() => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+
+/**
+ * Render a web component and wait for it to be ready
+ * Handles the full lifecycle: wait for definition, create, append, wait for render
+ *
+ * @param {string} tagName - Custom element tag name
+ * @param {Object} attributes - Attributes to set on the element
+ * @param {Object} properties - Properties to set on the element
+ * @param {HTMLElement} container - Container to append to (defaults to document.body)
+ * @returns {Promise<HTMLElement>} The custom element
+ *
+ * @example
+ * const chart = await renderWebComponent('pie-chart', {
+ *   type: 'bar',
+ *   'data-testid': 'my-chart'
+ * });
+ *
+ * @example
+ * const button = await renderWebComponent('custom-button',
+ *   { 'aria-label': 'Submit' },
+ *   { onClick: jest.fn() }
+ * );
+ */
+export async function renderWebComponent(
+  tagName,
+  attributes = {},
+  properties = {},
+  container = document.body
+) {
+  await waitForCustomElement(tagName);
+
+  const element = document.createElement(tagName);
+
+  // Set attributes (strings)
+  Object.entries(attributes).forEach(([key, value]) => {
+    element.setAttribute(key, value);
+  });
+
+  // Set properties (objects, functions, etc.)
+  Object.entries(properties).forEach(([key, value]) => {
+    element[key] = value;
+  });
+
+  container.appendChild(element);
+
+  // Wait for component to render (custom elements may be async)
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  return element;
+}
+
+/**
+ * Dispatch a custom event on an element
+ * Web components often use custom events for communication
+ *
+ * @param {HTMLElement} element - Element to dispatch event from
+ * @param {string} eventName - Event name (e.g., 'change', 'custom-event')
+ * @param {*} detail - Event detail data
+ * @param {Object} options - Event options (bubbles, composed, etc.)
+ *
+ * @example
+ * dispatchCustomEvent(chart, 'data-changed', { value: [1, 2, 3] });
+ *
+ * @example
+ * dispatchCustomEvent(button, 'custom-click', null, { bubbles: false });
+ */
+export function dispatchCustomEvent(
+  element,
+  eventName,
+  detail = null,
+  options = {}
+) {
+  const event = new CustomEvent(eventName, {
+    detail,
+    bubbles: true,
+    composed: true, // Allow event to cross shadow DOM boundary
+    ...options,
+  });
+
+  element.dispatchEvent(event);
+  return event;
+}
+
+/**
+ * Listen for a custom event and return a promise that resolves when fired
+ * Useful for testing event emissions
+ *
+ * @param {HTMLElement} element - Element to listen to
+ * @param {string} eventName - Event name to wait for
+ * @param {number} timeout - Timeout in milliseconds
+ * @returns {Promise<CustomEvent>} Promise that resolves with the event
+ *
+ * @example
+ * const promise = waitForEvent(chart, 'data-loaded');
+ * chart.loadData();
+ * const event = await promise;
+ * expect(event.detail).toEqual({ loaded: true });
+ *
+ * @example
+ * await waitForEvent(component, 'ready', 5000);
+ */
+export function waitForEvent(element, eventName, timeout = 3000) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      element.removeEventListener(eventName, handler);
+      reject(
+        new Error(`Event '${eventName}' not fired within ${timeout}ms`)
+      );
+    }, timeout);
+
+    const handler = (event) => {
+      clearTimeout(timer);
+      element.removeEventListener(eventName, handler);
+      resolve(event);
+    };
+
+    element.addEventListener(eventName, handler);
+  });
+}
+
+/**
+ * Check if a custom element is defined
+ * Useful for verifying element registration
+ *
+ * @param {string} tagName - Custom element tag name
+ * @returns {boolean} True if element is defined
+ *
+ * @example
+ * if (isCustomElementDefined('pie-chart')) {
+ *   // Element is ready to use
+ * }
+ */
+export function isCustomElementDefined(tagName) {
+  return typeof customElements !== 'undefined' && customElements.get(tagName) !== undefined;
+}
+
+/**
+ * Helper to create and configure a custom element
+ * For light DOM web components that render React
+ *
+ * @param {string} tagName - Custom element tag name
+ * @param {Object} props - Props to pass to the element
+ * @returns {HTMLElement} The custom element
+ *
+ * @example
+ * const chart = createCustomElement('pie-chart', {
+ *   data: [1, 2, 3],
+ *   type: 'bar'
+ * });
+ * document.body.appendChild(chart);
+ */
+export function createCustomElement(tagName, props = {}) {
+  const element = document.createElement(tagName);
+
+  // Set properties directly on the element
+  Object.entries(props).forEach(([key, value]) => {
+    element[key] = value;
+  });
+
+  return element;
+}