ai-qakit 1.0.0

package/templates/.cursor/rules/frontend-development/references/testing.md

@@ -0,0 +1,629 @@
+# Testing
+
+Vitest, React Testing Library, and MSW patterns for comprehensive React testing.
+
+---
+
+## Setup
+
+```bash
+npm install -D vitest @testing-library/react @testing-library/jest-dom @testing-library/user-event jsdom msw
+```
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['./src/test/setup.ts'],
+    include: ['src/**/*.{test,spec}.{ts,tsx}'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: ['node_modules/', 'src/test/', '**/*.d.ts'],
+    },
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+});
+```
+
+```ts
+// src/test/setup.ts
+import '@testing-library/jest-dom/vitest';
+import { cleanup } from '@testing-library/react';
+import { afterEach, beforeAll, afterAll } from 'vitest';
+import { server } from './mocks/server';
+
+// MSW setup
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
+afterEach(() => {
+  cleanup();
+  server.resetHandlers();
+});
+afterAll(() => server.close());
+```
+
+---
+
+## Test Utilities
+
+```tsx
+// src/test/utils.tsx
+import { render, RenderOptions } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { BrowserRouter } from 'react-router-dom';
+
+const createTestQueryClient = () =>
+  new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+        gcTime: 0,
+      },
+    },
+  });
+
+interface AllTheProvidersProps {
+  children: React.ReactNode;
+}
+
+const AllTheProviders: React.FC<AllTheProvidersProps> = ({ children }) => {
+  const queryClient = createTestQueryClient();
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        {children}
+      </BrowserRouter>
+    </QueryClientProvider>
+  );
+};
+
+const customRender = (
+  ui: React.ReactElement,
+  options?: Omit<RenderOptions, 'wrapper'>
+) => render(ui, { wrapper: AllTheProviders, ...options });
+
+export * from '@testing-library/react';
+export { customRender as render };
+```
+
+---
+
+## Component Testing
+
+### Basic Component Test
+
+```tsx
+// entities/user/ui/UserCard.test.tsx
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@/test/utils';
+import { UserCard } from './UserCard';
+
+const mockUser = {
+  id: '1',
+  name: 'John Doe',
+  email: 'john@example.com',
+  avatar: 'https://example.com/avatar.jpg',
+};
+
+describe('UserCard', () => {
+  it('renders user information', () => {
+    render(<UserCard user={mockUser} />);
+
+    expect(screen.getByText('John Doe')).toBeInTheDocument();
+    expect(screen.getByText('john@example.com')).toBeInTheDocument();
+  });
+
+  it('renders avatar with correct alt text', () => {
+    render(<UserCard user={mockUser} />);
+
+    const avatar = screen.getByRole('img');
+    expect(avatar).toHaveAttribute('alt', 'John Doe');
+  });
+
+  it('calls onClick when clicked', async () => {
+    const handleClick = vi.fn();
+    const { user } = render(<UserCard user={mockUser} onClick={handleClick} />);
+
+    await user.click(screen.getByRole('article'));
+
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('applies custom className', () => {
+    render(<UserCard user={mockUser} className="custom-class" />);
+
+    expect(screen.getByRole('article')).toHaveClass('custom-class');
+  });
+});
+```
+
+### Testing with User Events
+
+```tsx
+// features/auth/ui/LoginForm.test.tsx
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, waitFor } from '@/test/utils';
+import userEvent from '@testing-library/user-event';
+import { LoginForm } from './LoginForm';
+
+describe('LoginForm', () => {
+  it('submits form with valid data', async () => {
+    const user = userEvent.setup();
+    const onSubmit = vi.fn();
+    
+    render(<LoginForm onSubmit={onSubmit} />);
+
+    await user.type(screen.getByLabelText(/email/i), 'test@example.com');
+    await user.type(screen.getByLabelText(/password/i), 'password123');
+    await user.click(screen.getByRole('button', { name: /login/i }));
+
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledWith({
+        email: 'test@example.com',
+        password: 'password123',
+      });
+    });
+  });
+
+  it('displays validation errors', async () => {
+    const user = userEvent.setup();
+    render(<LoginForm onSubmit={vi.fn()} />);
+
+    // Submit empty form
+    await user.click(screen.getByRole('button', { name: /login/i }));
+
+    await waitFor(() => {
+      expect(screen.getByText(/email is required/i)).toBeInTheDocument();
+      expect(screen.getByText(/password is required/i)).toBeInTheDocument();
+    });
+  });
+
+  it('disables submit button while loading', async () => {
+    render(<LoginForm onSubmit={vi.fn()} isLoading />);
+
+    expect(screen.getByRole('button', { name: /loading/i })).toBeDisabled();
+  });
+});
+```
+
+---
+
+## Hook Testing
+
+```tsx
+// features/posts/model/usePost.test.ts
+import { describe, it, expect } from 'vitest';
+import { renderHook, waitFor } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { usePost } from './usePost';
+import { server } from '@/test/mocks/server';
+import { http, HttpResponse } from 'msw';
+
+const wrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+    </QueryClientProvider>
+  );
+};
+
+describe('usePost', () => {
+  it('fetches post data', async () => {
+    const mockPost = { id: '1', title: 'Test Post', content: 'Content' };
+
+    server.use(
+      http.get('/api/posts/1', () => {
+        return HttpResponse.json(mockPost);
+      })
+    );
+
+    const { result } = renderHook(() => usePost('1'), { wrapper });
+
+    await waitFor(() => {
+      expect(result.current.data).toEqual(mockPost);
+    });
+  });
+
+  it('handles error state', async () => {
+    server.use(
+      http.get('/api/posts/1', () => {
+        return HttpResponse.json({ message: 'Not found' }, { status: 404 });
+      })
+    );
+
+    const { result } = renderHook(() => usePost('1'), { wrapper });
+
+    await waitFor(() => {
+      expect(result.current.error).toBeDefined();
+    });
+  });
+});
+```
+
+---
+
+## MSW (Mock Service Worker)
+
+### Setup
+
+```ts
+// src/test/mocks/handlers.ts
+import { http, HttpResponse } from 'msw';
+
+export const handlers = [
+  // GET users
+  http.get('/api/users', () => {
+    return HttpResponse.json([
+      { id: '1', name: 'John Doe', email: 'john@example.com' },
+      { id: '2', name: 'Jane Smith', email: 'jane@example.com' },
+    ]);
+  }),
+
+  // GET single user
+  http.get('/api/users/:id', ({ params }) => {
+    return HttpResponse.json({
+      id: params.id,
+      name: 'John Doe',
+      email: 'john@example.com',
+    });
+  }),
+
+  // POST create user
+  http.post('/api/users', async ({ request }) => {
+    const body = await request.json();
+    return HttpResponse.json(
+      { id: '3', ...body },
+      { status: 201 }
+    );
+  }),
+
+  // DELETE user
+  http.delete('/api/users/:id', () => {
+    return new HttpResponse(null, { status: 204 });
+  }),
+];
+
+// src/test/mocks/server.ts
+import { setupServer } from 'msw/node';
+import { handlers } from './handlers';
+
+export const server = setupServer(...handlers);
+```
+
+### Override Handlers in Tests
+
+```tsx
+import { server } from '@/test/mocks/server';
+import { http, HttpResponse } from 'msw';
+
+it('handles server error', async () => {
+  server.use(
+    http.get('/api/users', () => {
+      return HttpResponse.json(
+        { message: 'Internal server error' },
+        { status: 500 }
+      );
+    })
+  );
+
+  render(<UsersList />);
+
+  await waitFor(() => {
+    expect(screen.getByText(/error/i)).toBeInTheDocument();
+  });
+});
+```
+
+---
+
+## Integration Testing
+
+```tsx
+// pages/users/UsersPage.test.tsx
+import { describe, it, expect } from 'vitest';
+import { render, screen, waitFor } from '@/test/utils';
+import userEvent from '@testing-library/user-event';
+import { UsersPage } from './UsersPage';
+import { server } from '@/test/mocks/server';
+import { http, HttpResponse } from 'msw';
+
+describe('UsersPage', () => {
+  it('displays list of users', async () => {
+    render(<UsersPage />);
+
+    await waitFor(() => {
+      expect(screen.getByText('John Doe')).toBeInTheDocument();
+      expect(screen.getByText('Jane Smith')).toBeInTheDocument();
+    });
+  });
+
+  it('filters users by search term', async () => {
+    const user = userEvent.setup();
+    render(<UsersPage />);
+
+    // Wait for initial load
+    await waitFor(() => {
+      expect(screen.getByText('John Doe')).toBeInTheDocument();
+    });
+
+    // Type in search
+    await user.type(screen.getByPlaceholderText(/search/i), 'Jane');
+
+    await waitFor(() => {
+      expect(screen.queryByText('John Doe')).not.toBeInTheDocument();
+      expect(screen.getByText('Jane Smith')).toBeInTheDocument();
+    });
+  });
+
+  it('creates new user', async () => {
+    const user = userEvent.setup();
+    
+    server.use(
+      http.post('/api/users', async ({ request }) => {
+        const body = await request.json() as { name: string; email: string };
+        return HttpResponse.json({
+          id: '3',
+          name: body.name,
+          email: body.email,
+        });
+      })
+    );
+
+    render(<UsersPage />);
+
+    // Open create modal
+    await user.click(screen.getByRole('button', { name: /create user/i }));
+
+    // Fill form
+    await user.type(screen.getByLabelText(/name/i), 'New User');
+    await user.type(screen.getByLabelText(/email/i), 'new@example.com');
+    await user.click(screen.getByRole('button', { name: /save/i }));
+
+    await waitFor(() => {
+      expect(screen.getByText('New User')).toBeInTheDocument();
+    });
+  });
+
+  it('deletes user', async () => {
+    const user = userEvent.setup();
+    render(<UsersPage />);
+
+    await waitFor(() => {
+      expect(screen.getByText('John Doe')).toBeInTheDocument();
+    });
+
+    // Click delete button
+    const deleteButtons = screen.getAllByRole('button', { name: /delete/i });
+    await user.click(deleteButtons[0]);
+
+    // Confirm deletion
+    await user.click(screen.getByRole('button', { name: /confirm/i }));
+
+    await waitFor(() => {
+      expect(screen.queryByText('John Doe')).not.toBeInTheDocument();
+    });
+  });
+});
+```
+
+---
+
+## Accessibility Testing
+
+```tsx
+import { axe, toHaveNoViolations } from 'jest-axe';
+
+expect.extend(toHaveNoViolations);
+
+describe('UserCard accessibility', () => {
+  it('has no accessibility violations', async () => {
+    const { container } = render(<UserCard user={mockUser} />);
+
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+});
+```
+
+---
+
+## Testing Patterns
+
+### Test Organization
+
+```tsx
+describe('ComponentName', () => {
+  describe('rendering', () => {
+    it('renders with required props', () => {});
+    it('renders with optional props', () => {});
+    it('renders loading state', () => {});
+    it('renders error state', () => {});
+  });
+
+  describe('interactions', () => {
+    it('handles click events', () => {});
+    it('handles form submission', () => {});
+    it('handles keyboard navigation', () => {});
+  });
+
+  describe('edge cases', () => {
+    it('handles empty data', () => {});
+    it('handles network errors', () => {});
+    it('handles invalid input', () => {});
+  });
+});
+```
+
+### Query Priorities
+
+```tsx
+// Accessible queries (preferred)
+screen.getByRole('button', { name: /submit/i });
+screen.getByLabelText(/email/i);
+screen.getByPlaceholderText(/search/i);
+screen.getByText(/welcome/i);
+screen.getByAltText(/profile/i);
+
+// Semantic queries
+screen.getByTitle(/close/i);
+
+// Test IDs (last resort)
+screen.getByTestId('custom-element');
+```
+
+### Async Patterns
+
+```tsx
+// Wait for element to appear
+await waitFor(() => {
+  expect(screen.getByText('Loaded')).toBeInTheDocument();
+});
+
+// Wait for element with find
+const element = await screen.findByText('Loaded');
+
+// Wait for element to disappear
+await waitFor(() => {
+  expect(screen.queryByText('Loading')).not.toBeInTheDocument();
+});
+
+// Wait for multiple conditions
+await waitFor(() => {
+  expect(screen.queryByText('Loading')).not.toBeInTheDocument();
+  expect(screen.getByText('Success')).toBeInTheDocument();
+});
+```
+
+---
+
+## Snapshot Testing
+
+```tsx
+import { render } from '@/test/utils';
+
+describe('Button', () => {
+  it('matches snapshot', () => {
+    const { container } = render(
+      <Button variant="primary">Click me</Button>
+    );
+
+    expect(container).toMatchSnapshot();
+  });
+
+  it('matches inline snapshot', () => {
+    const { container } = render(<Badge>New</Badge>);
+
+    expect(container.firstChild).toMatchInlineSnapshot(`
+      <span class="inline-flex items-center rounded-full bg-primary px-2 py-1 text-xs font-medium text-white">
+        New
+      </span>
+    `);
+  });
+});
+```
+
+---
+
+## Mocking
+
+### Mock Functions
+
+```tsx
+import { vi } from 'vitest';
+
+const mockFn = vi.fn();
+const mockImplementation = vi.fn().mockImplementation(() => 'result');
+const mockAsync = vi.fn().mockResolvedValue({ data: 'value' });
+const mockReject = vi.fn().mockRejectedValue(new Error('Failed'));
+
+// Assert calls
+expect(mockFn).toHaveBeenCalled();
+expect(mockFn).toHaveBeenCalledTimes(1);
+expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2');
+```
+
+### Mock Modules
+
+```tsx
+// Mock entire module
+vi.mock('@/shared/api', () => ({
+  apiClient: {
+    get: vi.fn(),
+    post: vi.fn(),
+  },
+}));
+
+// Mock specific export
+vi.mock('@/features/auth', async () => {
+  const actual = await vi.importActual('@/features/auth');
+  return {
+    ...actual,
+    useAuth: vi.fn(() => ({ user: { id: '1' }, isAuthenticated: true })),
+  };
+});
+```
+
+---
+
+## FSD Test Organization
+
+```
+src/
+├── entities/
+│   └── user/
+│       ├── ui/
+│       │   ├── UserCard.tsx
+│       │   └── UserCard.test.tsx
+│       └── model/
+│           ├── useUser.ts
+│           └── useUser.test.ts
+├── features/
+│   └── auth/
+│       ├── ui/
+│       │   ├── LoginForm.tsx
+│       │   └── LoginForm.test.tsx
+│       └── model/
+│           ├── useAuth.ts
+│           └── useAuth.test.ts
+├── pages/
+│   └── users/
+│       ├── UsersPage.tsx
+│       └── UsersPage.test.tsx
+└── test/
+    ├── setup.ts
+    ├── utils.tsx
+    └── mocks/
+        ├── handlers.ts
+        └── server.ts
+```
+
+---
+
+## Testing Checklist
+
+- [ ] Component renders correctly
+- [ ] Props are handled properly
+- [ ] User interactions work
+- [ ] Loading states display
+- [ ] Error states handled
+- [ ] Accessibility passes
+- [ ] Async operations complete
+- [ ] Edge cases covered
+- [ ] MSW handlers defined
+- [ ] No console errors in tests
+