React-Admin Test Utilities

Common errors

• Error: could not find react-redux context value; please ensure the component is wrapped in a <Provider>

  cause `react-admin` components require a Redux store context, which `TestContext` provides, but this error indicates it's missing.
  fix Ensure the component under test is wrapped within `<TestContext>` or rendered using `renderWithRedux`. For example: `render(<TestContext><MyComponent /></TestContext>)`

• Error: useLocation() may be used only in the context of a <Router> component.

  cause `react-admin` components often use React Router hooks, requiring a Router context that `TestContext` provides.
  fix The component depending on `react-router` hooks or components must be rendered inside `TestContext`, which sets up the necessary `react-router` context. For example: `render(<TestContext><MyComponentThatUsesRouter /></TestContext>)`

• TypeError: Cannot read properties of undefined (reading 'dispatch') or TypeError: Cannot read property 'dispatch' of undefined

  cause Attempting to spy on `store.dispatch` or interact with the Redux store when `TestContext` has not yet exposed it or when `enableReducers` is not set.
  fix If spying on `dispatch`, ensure you use the render prop pattern for `TestContext` to access the `store` object: `<TestContext>{({ store }) => { dispatchSpy = jest.spyOn(store, 'dispatch'); return <MyComponent />; }}</TestContext>`. Also, ensure `enableReducers` is set if state changes are expected.

Warnings

• breaking The `ra-test` package versions are tightly coupled with the major versions of `react-admin`. Using `ra-test@3.x.x` with `react-admin@4.x.x` or `5.x.x` will lead to incompatible APIs and runtime errors due to significant changes in `react-admin`'s internal structure and context providers.
  Fix: Ensure your `ra-test` package version matches the major version of your `react-admin` installation (e.g., `react-admin@5.x.x` requires `ra-test@5.x.x`). Upgrade both packages concurrently.
• gotcha Direct unit testing of most `react-admin`'s built-in components is generally discouraged by the framework maintainers. `ra-test` is primarily for custom components that integrate with `react-admin`'s context, rather than testing react-admin's internals.
  Fix: Focus your testing efforts on end-to-end scenarios for core application flows and on unit/integration testing your *custom* React components, mocking `react-admin`'s data providers or using `TestContext` for dependencies.
• gotcha `react-admin` components heavily rely on React Context for Redux, React Router, and internal framework state. Without wrapping components under test in `TestContext` (or `renderWithRedux`), they will fail to initialize or function correctly.
  Fix: Always wrap your `react-admin` dependent components with `TestContext` or use the `renderWithRedux` helper. Remember to enable reducers if your component relies on Redux state changes (`<TestContext enableReducers />`).
• deprecated The use of `TestContext` without `enableReducers` will prevent Redux actions from being processed, making tests for components that dispatch actions ineffective. While not strictly deprecated, it's a common oversight.
  Fix: If your component dispatches Redux actions or relies on Redux state updates, always pass the `enableReducers` prop to `TestContext`: `<TestContext enableReducers>{...}</TestContext>`.

Install

• npm install ra-test npm
• yarn add ra-test yarn
• pnpm add ra-test pnpm

Imports

• TestContext
  wrong:

  const { TestContext } = require('ra-test');

  correct:

  import { TestContext } from 'ra-test';

  The primary component for wrapping react-admin components to provide necessary context for testing. ESM imports are standard.
• renderWithRedux
  wrong:

  import renderWithRedux from 'ra-test';

  correct:

  import { renderWithRedux } from 'ra-test';

  A helper function that combines TestContext setup with @testing-library/react's render, exported as a named import.
• defaultStore

  import { defaultStore } from 'ra-test';

  Provides a default Redux store configuration that can be used or extended for tests, useful with enableReducers.

Quickstart

This quickstart demonstrates how to use `TestContext` to wrap a custom `react-admin` component, providing the necessary Redux and routing contexts for unit testing with `@testing-library/react`. It shows how to pass default props and simulate user interactions.

import * as React from "react";
import { TestContext } from 'ra-test';
import { render, fireEvent, screen } from '@testing-library/react';

// Imagine this is your custom react-admin Edit view component
const MyCustomEditView = ({ basePath, id, resource }) => {
    const handleClick = () => {
        // In a real app, this might dispatch an action or navigate
        console.log(`Action for resource ${resource} with ID ${id} at ${basePath}`);
    };
    return (
        <div data-testid="my-custom-edit-view">
            <h1>Edit {resource} #{id}</h1>
            <p>Base Path: {basePath}</p>
            <button onClick={handleClick}>Perform Action</button>
        </div>
    );
};

describe('MyCustomEditView', () => {
    const defaultEditProps = {
        basePath: '/posts',
        id: '123',
        resource: 'posts',
    };

    it('should render the custom edit view with provided props', () => {
        render(
            <TestContext enableReducers>
                <MyCustomEditView {...defaultEditProps} />
            </TestContext>
        );
        expect(screen.getByText('Edit posts #123')).toBeInTheDocument();
        expect(screen.getByText('Base Path: /posts')).toBeInTheDocument();
    });

    it('should simulate a button click', () => {
        const consoleSpy = jest.spyOn(console, 'log');
        render(
            <TestContext enableReducers>
                <MyCustomEditView {...defaultEditProps} />
            </TestContext>
        );
        fireEvent.click(screen.getByText('Perform Action'));
        expect(consoleSpy).toHaveBeenCalledWith('Action for resource posts with ID 123 at /posts');
        consoleSpy.mockRestore();
    });
});