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

package/CHANGELOG.md

@@ -7,129 +7,71 @@ See [Conventional Commits](https://conventionalcommits.org) for commit guideline
 
 **Note:** Version bump only for package @pie-lib/test-utils
 
-
-
-
-
 # [0.22.0](https://github.com/pie-framework/pie-lib/compare/@pie-lib/test-utils@0.18.0...@pie-lib/test-utils@0.22.0) (2025-10-16)
 
 **Note:** Version bump only for package @pie-lib/test-utils
 
-
-
-
-
 # [0.21.0](https://github.com/pie-framework/pie-lib/compare/@pie-lib/test-utils@0.18.0...@pie-lib/test-utils@0.21.0) (2025-10-16)
 
 **Note:** Version bump only for package @pie-lib/test-utils
 
-
-
-
-
 # [0.20.0](https://github.com/pie-framework/pie-lib/compare/@pie-lib/test-utils@0.18.0...@pie-lib/test-utils@0.20.0) (2025-10-16)
 
 **Note:** Version bump only for package @pie-lib/test-utils
 
-
-
-
-
 # [0.19.0](https://github.com/pie-framework/pie-lib/compare/@pie-lib/test-utils@0.18.0...@pie-lib/test-utils@0.19.0) (2025-10-16)
 
 **Note:** Version bump only for package @pie-lib/test-utils
 
-
-
-
-
 # [0.18.0](https://github.com/pie-framework/pie-lib/compare/@pie-lib/test-utils@0.2.33...@pie-lib/test-utils@0.18.0) (2025-09-25)
 
-
 ### Bug Fixes
 
-* fixed pie-lib/icons import [PD-5126] ([dcb506c](https://github.com/pie-framework/pie-lib/commit/dcb506c914a177f6d88bf73247a023bfe71dac1f))
-
+- fixed pie-lib/icons import [PD-5126](<[dcb506c](https://github.com/pie-framework/pie-lib/commit/dcb506c914a177f6d88bf73247a023bfe71dac1f)>)
 
 ### Features
 
-* split pie-toolbox into multiple packages [PD-5126] ([7d55a25](https://github.com/pie-framework/pie-lib/commit/7d55a2552d084cd3d0d5c00dc77411b2ced2f5e2))
-
-
-
-
+- split pie-toolbox into multiple packages [PD-5126](<[7d55a25](https://github.com/pie-framework/pie-lib/commit/7d55a2552d084cd3d0d5c00dc77411b2ced2f5e2)>)
 
 # [0.17.0](https://github.com/pie-framework/pie-lib/compare/@pie-lib/test-utils@0.16.0...@pie-lib/test-utils@0.17.0) (2025-09-18)
 
 **Note:** Version bump only for package @pie-lib/test-utils
 
-
-
-
-
 # [0.16.0](https://github.com/pie-framework/pie-lib/compare/@pie-lib/test-utils@0.15.0...@pie-lib/test-utils@0.16.0) (2025-09-18)
 
 **Note:** Version bump only for package @pie-lib/test-utils
 
-
-
-
-
 # [0.15.0](https://github.com/pie-framework/pie-lib/compare/@pie-lib/test-utils@0.2.33...@pie-lib/test-utils@0.15.0) (2025-09-18)
 
-
 ### Bug Fixes
 
-* fixed pie-lib/icons import [PD-5126] ([dcb506c](https://github.com/pie-framework/pie-lib/commit/dcb506c914a177f6d88bf73247a023bfe71dac1f))
-
+- fixed pie-lib/icons import [PD-5126](<[dcb506c](https://github.com/pie-framework/pie-lib/commit/dcb506c914a177f6d88bf73247a023bfe71dac1f)>)
 
 ### Features
 
-* split pie-toolbox into multiple packages [PD-5126] ([7d55a25](https://github.com/pie-framework/pie-lib/commit/7d55a2552d084cd3d0d5c00dc77411b2ced2f5e2))
-
-
-
-
+- split pie-toolbox into multiple packages [PD-5126](<[7d55a25](https://github.com/pie-framework/pie-lib/commit/7d55a2552d084cd3d0d5c00dc77411b2ced2f5e2)>)
 
 # [0.14.0](https://github.com/pie-framework/pie-lib/compare/@pie-lib/test-utils@0.13.0...@pie-lib/test-utils@0.14.0) (2025-09-17)
 
 **Note:** Version bump only for package @pie-lib/test-utils
 
-
-
-
-
 # [0.13.0](https://github.com/pie-framework/pie-lib/compare/@pie-lib/test-utils@0.12.0...@pie-lib/test-utils@0.13.0) (2025-09-17)
 
 **Note:** Version bump only for package @pie-lib/test-utils
 
-
-
-
-
 # [0.12.0](https://github.com/pie-framework/pie-lib/compare/@pie-lib/test-utils@0.11.1...@pie-lib/test-utils@0.12.0) (2025-09-17)
 
 **Note:** Version bump only for package @pie-lib/test-utils
 
-
-
-
-
 ## [0.11.1](https://github.com/pie-framework/pie-lib/compare/@pie-lib/test-utils@0.2.33...@pie-lib/test-utils@0.11.1) (2025-08-11)
 
-
 ### Bug Fixes
 
-* fixed pie-lib/icons import [PD-5126] ([dcb506c](https://github.com/pie-framework/pie-lib/commit/dcb506c914a177f6d88bf73247a023bfe71dac1f))
-
+- fixed pie-lib/icons import [PD-5126](<[dcb506c](https://github.com/pie-framework/pie-lib/commit/dcb506c914a177f6d88bf73247a023bfe71dac1f)>)
 
 ### Features
 
-* split pie-toolbox into multiple packages [PD-5126] ([7d55a25](https://github.com/pie-framework/pie-lib/commit/7d55a2552d084cd3d0d5c00dc77411b2ced2f5e2))
-
-
-
-
+- split pie-toolbox into multiple packages [PD-5126](<[7d55a25](https://github.com/pie-framework/pie-lib/commit/7d55a2552d084cd3d0d5c00dc77411b2ced2f5e2)>)
 
 # [0.11.0](https://github.com/pie-framework/pie-lib/compare/@pie-lib/test-utils@0.2.33...@pie-lib/test-utils@0.11.0) (2025-08-07)
 

package/README.md

@@ -0,0 +1,463 @@
+# @pie-lib/test-utils
+
+Testing utilities for pie-lib packages with React Testing Library and MUI support.
+
+## Installation
+
+This package is typically used as a dev dependency:
+
+```bash
+yarn add -D @pie-lib/test-utils
+```
+
+## Features
+
+- ✅ React Testing Library utilities
+- ✅ MUI Theme Provider wrapper for tests
+- ✅ Multiple provider composition
+- ✅ Custom theme creation for testing
+- ✅ All RTL exports in one place
+- ✅ userEvent and jest-dom matchers included
+- ✅ Keyboard helpers for keyCode-based components
+- ✅ Web component testing utilities (light DOM only)
+
+## Usage
+
+### Basic Rendering with MUI Theme
+
+```javascript
+import { renderWithTheme, screen } from '@pie-lib/test-utils';
+import { Button } from '@mui/material';
+
+test('renders a button', () => {
+  renderWithTheme(<Button>Click me</Button>);
+  expect(screen.getByRole('button')).toBeInTheDocument();
+});
+```
+
+### Custom Theme
+
+```javascript
+import { renderWithTheme, createTestTheme } from '@pie-lib/test-utils';
+
+test('renders with dark theme', () => {
+  const darkTheme = createTestTheme({
+    palette: { mode: 'dark' }
+  });
+
+  renderWithTheme(<MyComponent />, { theme: darkTheme });
+  // ... assertions
+});
+```
+
+### Multiple Providers
+
+```javascript
+import { renderWithProviders } from '@pie-lib/test-utils';
+
+test('renders with multiple providers', () => {
+  const ReduxProvider = ({ children }) => (
+    <Provider store={store}>{children}</Provider>
+  );
+
+  renderWithProviders(<MyComponent />, {
+    providers: [ReduxProvider]
+  });
+  // ... assertions
+});
+```
+
+### User Interactions
+
+```javascript
+import { renderWithTheme, screen, userEvent } from '@pie-lib/test-utils';
+
+test('handles button click', async () => {
+  const onClick = jest.fn();
+  const user = userEvent.setup();
+
+  renderWithTheme(<Button onClick={onClick}>Click</Button>);
+
+  await user.click(screen.getByRole('button'));
+  expect(onClick).toHaveBeenCalledTimes(1);
+});
+```
+
+### Keyboard Interactions
+
+**NEW:** Helper functions for testing keyboard events, especially useful for legacy components checking `event.keyCode`:
+
+```javascript
+import { render, screen, pressKey, Keys, typeAndSubmit } from '@pie-lib/test-utils';
+
+test('submits on Enter key', async () => {
+  const onSubmit = jest.fn();
+  render(<SearchInput onSubmit={onSubmit} />);
+
+  const input = screen.getByRole('textbox');
+  await typeAndSubmit(input, 'search term');
+
+  expect(onSubmit).toHaveBeenCalledWith('search term');
+});
+
+test('handles Escape key', () => {
+  const onCancel = jest.fn();
+  render(<Modal onCancel={onCancel} />);
+
+  const modal = screen.getByRole('dialog');
+  pressKey(modal, Keys.ESCAPE);
+
+  expect(onCancel).toHaveBeenCalled();
+});
+```
+
+### Async Operations
+
+```javascript
+import { renderWithTheme, screen, waitFor } from '@pie-lib/test-utils';
+
+test('loads data', async () => {
+  renderWithTheme(<AsyncComponent />);
+
+  // Wait for element to appear
+  const element = await screen.findByText('Loaded');
+  expect(element).toBeInTheDocument();
+
+  // Or use waitFor
+  await waitFor(() => {
+    expect(screen.getByText('Loaded')).toBeInTheDocument();
+  });
+});
+```
+
+### Web Component Testing
+
+**Note:** Utilities for testing custom elements with **light DOM** (no Shadow DOM). Standard React Testing Library queries work directly on these components.
+
+```javascript
+import { renderWebComponent, dispatchCustomEvent, screen } from '@pie-lib/test-utils';
+
+test('interacts with web component', async () => {
+  const element = await renderWebComponent('my-custom-element', {
+    'data-testid': 'my-element',
+    value: '42'
+  });
+
+  // Query using standard RTL queries (light DOM)
+  const button = screen.getByRole('button');
+  await user.click(button);
+
+  // Dispatch custom events
+  dispatchCustomEvent(element, 'value-changed', { newValue: '100' });
+});
+```
+
+## API Reference
+
+### React Component Rendering
+
+### `renderWithTheme(ui, options)`
+
+Renders a component wrapped with MUI ThemeProvider.
+
+**Parameters:**
+- `ui` - React component to render
+- `options.theme` - Custom MUI theme (optional, defaults to Material-UI default)
+- `options...` - Additional options passed to RTL's `render()`
+
+**Returns:** RTL render result
+
+### `renderWithProviders(ui, options)`
+
+Renders a component with MUI ThemeProvider and additional custom providers.
+
+**Parameters:**
+- `ui` - React component to render
+- `options.theme` - Custom MUI theme (optional)
+- `options.providers` - Array of provider components to wrap (optional)
+- `options...` - Additional options passed to RTL's `render()`
+
+**Returns:** RTL render result
+
+### `createTestTheme(themeOptions)`
+
+Creates a MUI theme for testing.
+
+**Parameters:**
+- `themeOptions` - MUI theme configuration object
+
+**Returns:** MUI theme object
+
+### `waitForRemoval(callback)`
+
+Alias for `waitForElementToBeRemoved` from RTL.
+
+### Re-exports
+
+This package re-exports everything from:
+- `@testing-library/react` (render, screen, waitFor, etc.)
+- `@testing-library/user-event` (as `userEvent`)
+- `@testing-library/jest-dom` (for TypeScript support)
+
+---
+
+## Keyboard Helpers API
+
+### `Keys`
+
+Constants for common keyboard key codes:
+
+```javascript
+import { Keys } from '@pie-lib/test-utils';
+
+Keys.ENTER      // 13
+Keys.ESCAPE     // 27
+Keys.SPACE      // 32
+Keys.TAB        // 9
+Keys.ARROW_DOWN // 40
+Keys.ARROW_UP   // 38
+// ... and more
+```
+
+### `pressKey(element, keyCode, type, options)`
+
+Simulate keyboard event with keyCode (useful for legacy components):
+
+```javascript
+import { pressKey, Keys } from '@pie-lib/test-utils';
+
+// Press Enter
+pressKey(input, Keys.ENTER);
+
+// Press Escape with keyup event
+pressKey(dialog, Keys.ESCAPE, 'keyup');
+
+// Press Ctrl+Enter
+pressKey(input, Keys.ENTER, 'keydown', { ctrlKey: true });
+```
+
+**Why?** `userEvent.type()` with `{Enter}` doesn't work well with components checking `event.keyCode`.
+
+### `typeAndSubmit(element, text)`
+
+Type text and press Enter (common pattern):
+
+```javascript
+import { typeAndSubmit } from '@pie-lib/test-utils';
+
+await typeAndSubmit(input, 'search query');
+// Types "search query" and presses Enter
+```
+
+### `clearAndType(element, text)`
+
+Clear input and type new text:
+
+```javascript
+import { clearAndType } from '@pie-lib/test-utils';
+
+await clearAndType(input, 'new value');
+```
+
+### `navigateWithKeys(element, steps, direction)`
+
+Navigate with arrow keys:
+
+```javascript
+import { navigateWithKeys } from '@pie-lib/test-utils';
+
+// Navigate down 3 items
+navigateWithKeys(listbox, 3, 'vertical');
+
+// Navigate left 2 items
+navigateWithKeys(tabs, -2, 'horizontal');
+```
+
+---
+
+## Web Component Helpers API
+
+**Note:** These utilities are for **light DOM web components only** (no Shadow DOM). For Shadow DOM components, use standard DOM queries or other testing libraries.
+
+### `waitForCustomElement(tagName, timeout)`
+
+Wait for custom element to be defined:
+
+```javascript
+import { waitForCustomElement } from '@pie-lib/test-utils';
+
+await waitForCustomElement('my-component');
+await waitForCustomElement('pie-chart', 5000); // 5 second timeout
+```
+
+### `renderWebComponent(tagName, attributes, properties, container)`
+
+Render web component and wait for it to be ready:
+
+```javascript
+import { renderWebComponent } from '@pie-lib/test-utils';
+
+const element = await renderWebComponent('pie-chart',
+  { type: 'bar', 'data-testid': 'chart' },  // attributes
+  { onDataChange: jest.fn() }               // properties
+);
+```
+
+### `dispatchCustomEvent(element, eventName, detail, options)`
+
+Dispatch custom event on element:
+
+```javascript
+import { dispatchCustomEvent } from '@pie-lib/test-utils';
+
+dispatchCustomEvent(chart, 'data-changed', { value: [1, 2, 3] });
+```
+
+### `waitForEvent(element, eventName, timeout)`
+
+Wait for custom event to be fired:
+
+```javascript
+import { waitForEvent } from '@pie-lib/test-utils';
+
+const promise = waitForEvent(component, 'ready');
+component.initialize();
+const event = await promise;
+expect(event.detail).toEqual({ initialized: true });
+```
+
+### `isCustomElementDefined(tagName)`
+
+Check if a custom element is defined:
+
+```javascript
+import { isCustomElementDefined } from '@pie-lib/test-utils';
+
+if (isCustomElementDefined('pie-chart')) {
+  // Element is ready to use
+}
+```
+
+### `createCustomElement(tagName, props)`
+
+Create and configure a custom element:
+
+```javascript
+import { createCustomElement } from '@pie-lib/test-utils';
+
+const chart = createCustomElement('pie-chart', {
+  data: [1, 2, 3],
+  type: 'bar'
+});
+document.body.appendChild(chart);
+```
+
+## Migration from Enzyme
+
+### Before (Enzyme)
+
+```javascript
+import { shallow } from 'enzyme';
+
+const wrapper = shallow(<Component />);
+expect(wrapper.find('button')).toHaveLength(1);
+wrapper.find('button').simulate('click');
+```
+
+### After (React Testing Library)
+
+```javascript
+import { renderWithTheme, screen, userEvent } from '@pie-lib/test-utils';
+
+renderWithTheme(<Component />);
+const button = screen.getByRole('button');
+expect(button).toBeInTheDocument();
+await userEvent.click(button);
+```
+
+## Query Priority
+
+Use queries in this order (best to worst):
+
+1. **getByRole** - Best for accessibility
+2. **getByLabelText** - Good for form fields
+3. **getByPlaceholderText** - Forms when label not available
+4. **getByText** - Non-interactive content
+5. **getByDisplayValue** - Current form values
+6. **getByAltText** - Images
+7. **getByTitle** - When other options don't work
+8. **getByTestId** - Last resort
+
+## Common Patterns
+
+### Testing Forms
+
+```javascript
+import { renderWithTheme, screen, userEvent } from '@pie-lib/test-utils';
+
+test('submits form', async () => {
+  const onSubmit = jest.fn();
+  const user = userEvent.setup();
+
+  renderWithTheme(<LoginForm onSubmit={onSubmit} />);
+
+  await user.type(screen.getByLabelText('Username'), 'user123');
+  await user.type(screen.getByLabelText('Password'), 'pass123');
+  await user.click(screen.getByRole('button', { name: /submit/i }));
+
+  expect(onSubmit).toHaveBeenCalledWith({
+    username: 'user123',
+    password: 'pass123'
+  });
+});
+```
+
+### Testing Conditional Rendering
+
+```javascript
+test('shows error message', async () => {
+  renderWithTheme(<Component />);
+
+  // Initially not present
+  expect(screen.queryByText('Error')).not.toBeInTheDocument();
+
+  // Trigger error
+  await userEvent.click(screen.getByRole('button'));
+
+  // Now appears
+  expect(await screen.findByText('Error occurred')).toBeInTheDocument();
+});
+```
+
+### Testing with Custom Props
+
+```javascript
+const defaultProps = {
+  title: 'Test',
+  onChange: jest.fn()
+};
+
+test('renders with defaults', () => {
+  renderWithTheme(<Component {...defaultProps} />);
+  expect(screen.getByText('Test')).toBeInTheDocument();
+});
+
+test('renders with overrides', () => {
+  renderWithTheme(<Component {...defaultProps} title="Override" />);
+  expect(screen.getByText('Override')).toBeInTheDocument();
+});
+```
+
+## Tips
+
+1. **Use `screen` queries** - More readable than destructuring from render
+2. **Prefer `findBy` for async** - Built-in waiting
+3. **Use `queryBy` for non-existence** - Won't throw if not found
+4. **Test behavior, not implementation** - Don't test internal state
+5. **Use `userEvent` over `fireEvent`** - More realistic interactions
+
+## Learn More
+
+- [React Testing Library Docs](https://testing-library.com/react)
+- [Common Mistakes](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library)
+- [MUI Testing Guide](https://mui.com/material-ui/guides/testing/)