Skip to content

reactive/data-client / .agents/skills/data-client-react-testing

data-client-react-testing

Verified

Test React code that uses @data-client/react: components and hooks that fetch or change data, with mocked responses for loading, error, mutation and polling cases. Covers renderDataHook, MockResolver and fixtures.

---
name: data-client-react-testing
description: "Test React code that uses @data-client/react: components and hooks that fetch or change data, with mocked responses for loading, error, mutation and polling cases. Covers renderDataHook, MockResolver and fixtures."
license: Apache 2.0
---

# Testing Patterns (@data-client/test)

These helpers come from `@data-client/test`. If `package.json` doesn't list it, add it as a dev dependency with the
project's package manager (`npm install -D @data-client/test`).

## Hook Testing with renderDataHook()

```typescript
import { renderDataHook } from '@data-client/test';

it('useSuspense() should render the response', async () => {
  const { result, waitFor } = renderDataHook(
    () => useSuspense(ArticleResource.get, { id: 5 }),
    {
      initialFixtures: [
        {
          endpoint: ArticleResource.get,
          args: [{ id: 5 }],
          response: { id: 5, title: 'hi ho', content: 'whatever' },
        },
      ],
    },
  );
  expect(result.current.title).toBe('hi ho');
});
```

**Options:**
- `initialFixtures` - Set up initial state of the store
- `resolverFixtures` - Add interceptors for subsequent requests
- `getInitialInterceptorData` - Simulate changing server state

**Return values:**
- Inherits all `renderHook()` return values from `@testing-library/react`
- `controller` - Controller instance for manual actions
- `allSettled()` - Wait for all async operations to complete

**Cleanup is automatic** -- an `afterEach` hook is registered at module load time that drains all active cleanups. Call the `cleanup()` a `renderDataHook()` call returns only to control cleanup order, such as before `jest.useRealTimers()`.

## Fixtures and Interceptors

**Success Fixture:**
```typescript
interface SuccessFixture {
  endpoint;
  args;
  response;
  error?;
  delay?;
}
```

**Response Interceptor:**
```typescript
interface ResponseInterceptor {
  endpoint;
  response(...args);
  delay?;
  delayCollapse?;
}
```

## Testing Mutations

**Create operations:**
```typescript
it('should create a new todo', async () => {
  const { result } = renderDataHook(
    () => useController(),
    {
      initialFixtures: [
        {
          endpoint: TodoResource.getList,
          args: [],
          response: [],
        },
      ],
      resolverFixtures: [
        {
          endpoint: TodoResource.getList.push,
          response: (newTodo) => ({ ...newTodo, id: 1 }),
        },
      ],
    },
  );

  const newTodo = { title: 'Test Todo', completed: false };
  const createdTodo = await result.current.fetch(TodoResource.getList.push, newTodo);
  
  expect(createdTodo.id).toBe(1);
});
```

## Testing Error States

```typescript
it('should handle fetch errors', async () => {
  const { result, waitFor } = renderDataHook(
    () => useSuspense(TodoResource.get, { id: 1 }),
    {
      initialFixtures: [
        {
          endpoint: TodoResource.get,
          args: [{ id: 1 }],
          response: null,
          error: new Error('Not found'),
        },
      ],
    },
  );

  await waitFor(() => {
    expect(result.current).toBeUndefined();
  });
});
```

## Testing Components

Use `MockResolver` to provide fixture data when rendering components with `DataProvider`:

```typescript
import { render } from '@testing-library/react';
import { DataProvider } from '@data-client/react';
import { MockResolver } from '@data-client/test';

it('should render todo list', async () => {
  const fixtures = [
    {
      endpoint: TodoResource.getList,
      args: [],
      response: [{ id: 1, title: 'Test Todo', completed: false }],
    },
  ];

  const { getByText } = render(
    <DataProvider>
      <MockResolver fixtures={fixtures}>
        <TodoList />
      </MockResolver>
    </DataProvider>,
  );

  expect(getByText('Test Todo')).toBeInTheDocument();
});
```

## Testing with nock (HTTP Endpoint Testing)

```typescript
import nock from 'nock';

it('should fetch data from API', async () => {
  const scope = nock('https://jsonplaceholder.typicode.com')
    .get('/todos/1')
    .reply(200, { id: 1, title: 'Test', completed: false });

  const result = await TodoResource.get({ id: 1 });
  
  expect(result.title).toBe('Test');
  scope.done();
});
```

## Testing Managers

Pass `managers` a function that returns new Managers; it runs once per `renderDataHook()` call. They replace the
defaults and must include a `NetworkManager`. Put your Manager before `NetworkManager` to
see `fetch` actions: `NetworkManager` handles them without passing them on.

```typescript
import { NetworkManager, useController } from '@data-client/react';
import type { Manager } from '@data-client/react';

it('should handle manager middleware', async () => {
  const types: string[] = [];
  const mockManager: Manager = {
    middleware: () => (next) => (action) => {
      types.push(action.type);
      return next(action);
    },
    cleanup: jest.fn(),
  };

  const { controller, cleanup } = renderDataHook(() => useController(), {
    managers: () => [mockManager, new NetworkManager()],
  });

  await controller.setResponse(
    TodoResource.get,
    { id: 1 },
    { id: 1, title: 'Test', completed: false },
  );
  expect(types).toEqual(['rdc/setresponse']);

  cleanup();
  expect(mockManager.cleanup).toHaveBeenCalled();
});
```

## Test File Organization

**Keep tests under `packages/*/src/**/__tests__`:**
```
packages/react/src/hooks/__tests__/useSuspense.test.ts
packages/react/src/components/__tests__/DataProvider.test.tsx
```

**Test naming** (files in `__tests__/`; elsewhere add `.test` before the suffix, e.g. `*.test.node.ts[x]`):
- Node-only: `*.node.ts[x]`
- React Native: `*.native.ts[x]`
- Regular: `*.ts[x]`

## Best Practices

- Use `renderDataHook()` for testing hooks that use @data-client/react hooks
- Use fixtures or interceptors when testing hooks or components
- Use `nock` when testing networking definitions
- Test both success and error scenarios
- Test mutations and their side effects
- Don't mock @data-client internals directly
- Don't use raw fetch in tests when fixtures are available
- Don't call `cleanup()` in `afterEach` -- cleanup is automatic
- Don't `jest.mock()` a whole `@data-client/*` module (`TypeError: Class extends value undefined`): use fixtures or a
  partial mock
- `fetch is not defined` under Jest: add the `whatwg-fetch` polyfill in `setupFiles`
  ([setup](references/unit-testing-hooks.md))

## References

For detailed API documentation, see the [references](references/) directory:

- [renderDataHook](references/renderDataHook.md) - Hook testing utility
- [makeRenderDataHook](references/makeRenderDataHook.md) - Custom hook renderer
- [Fixtures](references/Fixtures.md) - Fixture format reference
- [MockResolver](references/MockResolver.md) - Component testing wrapper
- [mockInitialState](references/mockInitialState.md) - Create initial state
- [unit-testing-hooks](references/unit-testing-hooks.md) - Jest setup and a full `renderDataHook()` test file
- [unit-testing-components](references/unit-testing-components.md) - A full component test file with `mockInitialState()` fixtures
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall