.cursor/rules/tanstack-react-query-tests.mdc - main - githubmirror/trpc

.cursor/rules/tanstack-react-query-tests.mdc
126 строк3 KB
Alex / KATT
chore: add some cursor rules (#6929)
05 сен 2025, 18:14
05 сен 2025, 18:140f12fc4
---
description: tRPC TanStack React Query testing patterns using testReactResource
globs: ['packages/tanstack-react-query/**/*.test.tsx']
alwaysApply: false
---

# tRPC TanStack React Query Testing Patterns

## TanStack React Query Specific Testing

### ALWAYS use testReactResource from local \_\_helpers

- **ALWAYS** use `await using ctx = testReactResource()` for TanStack React Query tests
- Import `testReactResource` from `./__helpers` (not from other packages)
- This provides TanStack-specific context creation and provider setup

### Test Resource Management

```typescript
// ✅ CORRECT: Use await using for automatic cleanup
await using ctx = testReactResource(appRouter, {
  server: {
    // server configuration
  },
  client(opts) {
    return {
      links: [
        httpLink({
          url: opts.httpUrl,
          // client configuration
        }),
      ],
    };
  },
});
```

### TanStack React Query Specific APIs

- Use `ctx.useTRPC()` for the TanStack React Query hooks
- Use `ctx.useTRPCClient()` for vanilla client access
- Use `ctx.optionsProxyClient` for options proxy functionality
- Use `ctx.optionsProxyServer` for server-side options proxy

### Test Structure for TanStack React Query

```typescript
test('tanstack react query test', async () => {
  await using ctx = testReactResource(appRouter);

  function MyComponent() {
    const query = ctx.useTRPC().post.byId.useQuery({ id: '1' });

    return (
      <div>
        {query.data ? `Result: ${query.data}` : 'Loading...'}
      </div>
    );
  }

  const utils = ctx.renderApp(<MyComponent />);

  await vi.waitFor(() => {
    expect(utils.container).toHaveTextContent('Result:');
  });
});
```

### Provider Setup

- Uses `TRPCProvider` from `createTRPCContext()`
- Wraps with `QueryClientProvider` from `@tanstack/react-query`
- Access via `ctx.renderApp()` and `ctx.rerenderApp()`

### Testing Helper Context Pattern

```typescript
const testContext = () => {
  const t = initTRPC.create({});

  const appRouter = t.router({
    // router definition
  });

  return {
    ...testReactResource(appRouter),
    // additional TanStack-specific utilities
  };
};
```

### Import Requirements for TanStack React Query

#### Test Helper Imports

- **ALWAYS** import `testReactResource` from `./__helpers` (local to tanstack-react-query package)
- **NEVER** import from other packages' helpers - each package has its own implementation
- Path: `import { testReactResource } from './__helpers';`

#### Other Required Imports

- Import `@testing-library/react` for rendering utilities
- Import `@testing-library/user-event` for user interactions
- Import React Query types from `@tanstack/react-query`
- Import TanStack React Query utilities from `../src`
- Import React testing utilities: `import * as React from 'react';`

### Key Differences from Legacy React Query

- Uses newer TanStack React Query provider pattern
- Has `optionsProxyClient` and `optionsProxyServer` for options proxy testing
- Uses `createTRPCContext()` instead of older React Query patterns
- More streamlined context creation and provider setup

### Helper Import Comparison

```typescript
// ✅ TanStack React Query (this package)
import { testReactResource } from './__helpers';

// ❌ DON'T use legacy React Query pattern
import { createAppRouter } from './__testHelpers'; // Wrong package

// ❌ DON'T use upgrade package pattern
import { testReactResource } from './test/__helpers'; // Wrong path
```