uui-unit-testing

# UUI Unit Testing UUI uses Jest with jsdom for unit testing React components. Tests are located in `__tests__` folders within each package. ## Test File Location Test files follow the pattern: `**/__tests__/**/*.test.{js,ts,tsx}` **Examples:** - `uui/components/buttons/__tests__/Button.test.tsx` - `uui/components/inputs/__tests__/NumericInput.test.tsx` - `uui-core/src/hooks/__tests__/useVirtualList.test.tsx` ## Test Commands **Run all tests:** ```bash yarn test ``` **Run tests in watch mode:** ```bash yarn test-watch ``` **Run a single test file:** ```bash yarn test -- --testPathPattern="Button" ``` Use `--testPathPattern` to match file path, or `--testNamePattern="should render"` to match test names. **Update snapshots:** ```bash yarn test-update ``` **Generate test coverage report:** ```bash yarn test-report ``` Coverage report saves to `.reports/unit-tests` folder. **TypeScript type checking:** ```bash yarn test-typecheck ``` **Windows workaround:** If encountering test errors on Windows, use reduced worker count: ```bash yarn test --maxWorkers=2 --testTimeout=10000 ``` You can increase `maxWorkers` up to 4 if needed. ## Using @epam/uui-test-utils The `@epam/uui-test-utils` package provides helpers for testing UUI components with proper context. ### Key Exports | Export | Purpose | |--------|---------| | `renderSnapshotWithContextAsync` | Render with UUI context, returns `DocumentFragment` for snapshots | | `renderWithContextAsync` | Render with UUI context for interaction testing | | `renderHookWithContextAsync` | Test custom hooks with UUI context | | `setupComponentForTest` | Setup component with mocks and `setProps` helper | | `screen` | Re-exported from `@testing-library/react` | | `userEvent` | Re-exported from `@testing-library/user-event` | | `fireEvent` | Re-exported from `@testing-library/react` | | `SvgMock` | Mock for SVG icon imports in snapshots | | `mockReactPortalsForSnapshots` | Mock portals for snapshot tests | | `delay`, `delayAct` | Async timing utilities for tests | ### renderSnapshotWithContextAsync Renders component with UUI context and returns a `DocumentFragment` (via `asFragment()`) for snapshot matching: ```typescript import { renderSnapshotWithContextAsync } from '@epam/uui-test-utils'; import { NumericInput } from '../NumericInput'; it('should be rendered with minimum props', async () => { const tree = await renderSnapshotWithContextAsync( <NumericInput value={null} onValueChange={jest.fn} min={0} max={50} /> ); expect(tree).toMatchSnapshot(); }); ``` ### setupComponentForTest Use for testing **controlled components** (e.g. `value` + `onValueChange`). Provides `setProps` to update props without unmounting, and `mocks` for callback assertions. Call `context.current.setProperty(name, value)` in callback mocks to simulate controlled updates: ```typescript import { setupComponentForTest, screen, fireEvent } from '@epam/uui-test-utils'; import { TextInput } from '@epam/uui'; interface TestComponentProps { value?: string; onValueChange?: (value: string) => void; } const { mocks, setProps } = await setupComponentForTest<TestComponentProps>( (context) => ({ value: 'initial', onValueChange: jest.fn().mockImplementation((newValue) => { context.current.setProperty('value', newValue); }), }), (props) => <TextInput value={props.value} onValueChange={props.onValueChange} />, ); const input = screen.queryByRole('textbox'); fireEvent.change(input, { target: { value: 'updated' } }); expect(mocks.onValueChange).toHaveBeenLastCalledWith('updated'); setProps({ value: 'external' }); // Update props without unmounting ``` ### renderHookWithContextAsync Renders a hook with UUI context. Returns `{ result, rerender, unmount, svc }`: - **result** — current hook return value (use `result.current`) - **svc** — UUI services (api, modals, router, etc.) for mocking or assertions - **rerender**, **unmount** — same as `renderHook` from Testing Library ```typescript import { renderHookWithContextAsync, act } from '@epam/uui-test-utils'; it('should use DataSource view', async () => { const dataSource = useArrayDataSource({ items: [...], getId: (i) => i.id }, []); const { result, svc } = await renderHookWithContextAsync(() => dataSource.useView({}, () => {}, {}) ); const rows = result.current.getVisibleRows(); expect(rows).toHaveLength(5); // svc.api, svc.uuiModals, etc. available for mocks }); it('should test custom hook with services', async () => { const { result, svc } = await renderHookWithContextAsync(useMyHook); act(() => result.current.doSomething()); expect(svc.uuiAnalytics.sendEvent).toHaveBeenCalled(); }); ``` ### renderWithContextAsync Renders component with UUI context for interaction testing: ```typescript import { renderWithContextAsync, screen, userEvent } from '@epam/uui-test-utils'; import { Tag } from '../Tag'; it('should call onClear callback', async () => { const onClearMock = jest.fn(); await renderWithContextAsync( <Tag caption="Test badge" onClear={onClearMock} /> ); const clearButton = await screen.findByRole('button', { name: /remove tag/i }); await userEvent.click(clearButton); expect(onClearMock).toHaveBeenCalled(); }); ``` ## Test Structure ### Basic Snapshot Test ```typescript import React from 'react'; import { ComponentName } from '../ComponentName'; import { renderSnapshotWithContextAsync } from '@epam/uui-test-utils'; describe('ComponentName', () => { describe('snapshots', () => { it('should be rendered with minimum props', async () => { const tree = await renderSnapshotWithContextAsync(<ComponentName />); expect(tree).toMatchSnapshot(); }); it('should be rendered with maximum props', async () => { const tree = await renderSnapshotWithContextAsync( <ComponentName prop1="value1" prop2="value2" /> ); expect(tree).toMatchSnapshot(); }); }); }); ``` ### Interaction Test ```typescript import { renderWithContextAsync, screen, userEvent } from '@epam/uui-test-utils'; it('should handle user interaction', async () => { const onActionMock = jest.fn(); await renderWithContextAsync( <ComponentName onAction={onActionMock} /> ); const button = await screen.findByRole('button'); await userEvent.click(button); expect(onActionMock).toHaveBeenCalled(); }); ``` ## Snapshot Update Workflow When UI changes require snapshot updates: 1. **Run tests** to see which snapshots fail: ```bash yarn test ``` 2. **Review changes** - verify the visual changes are intentional 3. **Update snapshots**: ```bash yarn test-update ``` 4. **Commit updated snapshots** along with component changes **Important:** Always review snapshot diffs before updating. Snapshots should reflect intentional UI changes, not accidental regressions. ## Test Environment - **Test framework:** Jest - **Test environment:** jsdom (for React components), node (for build scripts) - **Test utilities:** `@epam/uui-test-utils` for component testing helpers ## Test Coverage Test coverage is collected from: - `uui-core` - `uui-components` - `uui` - `epam-promo` - `epam-electric` - `loveship` Run `yarn test-report` to generate coverage reports. ## Common Patterns ### Mocking Portals for Snapshots Use the built-in helper instead of manual mocking: ```typescript import { mockReactPortalsForSnapshots, renderSnapshotWithContextAsync } from '@epam/uui-test-utils'; describe('ComponentWithPortal', () => { mockReactPortalsForSnapshots(); it('should render correctly', async () => { const tree = await renderSnapshotWithContextAsync(<MyModal />); expect(tree).toMatchSnapshot(); }); }); ``` ### Testing with Icons Use `SvgMock` from test utils for icon props in snapshots: ```typescript import { SvgMock, renderSnapshotWithContextAsync } from '@epam/uui-test-utils'; it('should render with icon', async () => { const tree = await renderSnapshotWithContextAsync( <Component icon={ SvgMock } /> ); expect(tree).toMatchSnapshot(); }); ``` For specific icon imports (when behavior depends on the icon): ```typescript // @ts-expect-error import { ReactComponent as CalendarIcon } from '@epam-assets/icons/action-calendar-fill.svg'; ``` ## Best Practices 1. **Add tests for bug fixes** - Prevent regressions 2. **Add tests for new functionality** - Ensure components work as expected 3. **Update snapshots when UI changes** - Keep snapshots current 4. **Run full test suite before committing** - `yarn test` 5. **Use descriptive test names** - Make failures easy to understand 6. **Test user interactions** - Not just rendering, but behavior ## References - Test utilities: `@epam/uui-test-utils` package - Example snapshot test: `uui/components/inputs/__tests__/NumericInput.test.tsx` - Example interaction test: `uui/components/widgets/__tests__/Tag.test.tsx` - Example setupComponentForTest: `app/src/docs/_examples/testing/__tests__/testComponent.test.tsx` - Example renderHookWithContextAsync: `uui-core/src/data/forms/__tests__/useForm.test.tsx` - Testing documentation: https://uui.epam.com/documents?id=testing-getting-started&mode=doc&isSkin=null&category=testing