@girardmedia/bootspring 1.1.0

package/agents/testing-expert/context.md

@@ -0,0 +1,414 @@
+# Testing Expert Agent
+
+## Role
+Specialized in testing strategies, test frameworks (Vitest, Jest, Playwright), test patterns, and ensuring code quality through comprehensive test coverage.
+
+## Core Expertise
+
+### Vitest Setup & Configuration
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+import tsconfigPaths from 'vite-tsconfig-paths';
+
+export default defineConfig({
+  plugins: [react(), tsconfigPaths()],
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['./tests/setup.ts'],
+    include: ['**/*.{test,spec}.{ts,tsx}'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: ['node_modules', 'tests/setup.ts'],
+    },
+  },
+});
+
+// tests/setup.ts
+import '@testing-library/jest-dom';
+import { vi } from 'vitest';
+
+// Mock Next.js router
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({
+    push: vi.fn(),
+    replace: vi.fn(),
+    back: vi.fn(),
+  }),
+  usePathname: () => '/',
+  useSearchParams: () => new URLSearchParams(),
+}));
+```
+
+### Unit Testing
+
+```typescript
+// lib/utils.test.ts
+import { describe, it, expect, vi } from 'vitest';
+import { formatCurrency, calculateDiscount, validateEmail } from './utils';
+
+describe('formatCurrency', () => {
+  it('formats positive numbers correctly', () => {
+    expect(formatCurrency(1234.56)).toBe('$1,234.56');
+  });
+
+  it('handles zero', () => {
+    expect(formatCurrency(0)).toBe('$0.00');
+  });
+
+  it('formats negative numbers', () => {
+    expect(formatCurrency(-50)).toBe('-$50.00');
+  });
+});
+
+describe('calculateDiscount', () => {
+  it('applies percentage discount', () => {
+    expect(calculateDiscount(100, { type: 'percentage', value: 20 })).toBe(80);
+  });
+
+  it('applies fixed discount', () => {
+    expect(calculateDiscount(100, { type: 'fixed', value: 15 })).toBe(85);
+  });
+
+  it('does not go below zero', () => {
+    expect(calculateDiscount(10, { type: 'fixed', value: 20 })).toBe(0);
+  });
+});
+
+describe('validateEmail', () => {
+  it.each([
+    ['user@example.com', true],
+    ['user.name+tag@example.co.uk', true],
+    ['invalid', false],
+    ['missing@domain', false],
+    ['@nodomain.com', false],
+  ])('validates %s as %s', (email, expected) => {
+    expect(validateEmail(email)).toBe(expected);
+  });
+});
+```
+
+### Component Testing
+
+```typescript
+// components/Button.test.tsx
+import { render, screen, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect, vi } from 'vitest';
+import { Button } from './Button';
+
+describe('Button', () => {
+  it('renders with children', () => {
+    render(<Button>Click me</Button>);
+    expect(screen.getByRole('button')).toHaveTextContent('Click me');
+  });
+
+  it('calls onClick when clicked', async () => {
+    const handleClick = vi.fn();
+    const user = userEvent.setup();
+
+    render(<Button onClick={handleClick}>Click me</Button>);
+    await user.click(screen.getByRole('button'));
+
+    expect(handleClick).toHaveBeenCalledOnce();
+  });
+
+  it('is disabled when loading', () => {
+    render(<Button isLoading>Submit</Button>);
+    expect(screen.getByRole('button')).toBeDisabled();
+  });
+
+  it('shows loading spinner when loading', () => {
+    render(<Button isLoading>Submit</Button>);
+    expect(screen.getByTestId('loading-spinner')).toBeInTheDocument();
+  });
+
+  it('applies variant classes', () => {
+    render(<Button variant="destructive">Delete</Button>);
+    expect(screen.getByRole('button')).toHaveClass('bg-destructive');
+  });
+});
+```
+
+### Form Testing
+
+```typescript
+// components/LoginForm.test.tsx
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect, vi } from 'vitest';
+import { LoginForm } from './LoginForm';
+
+describe('LoginForm', () => {
+  const mockOnSubmit = vi.fn();
+
+  beforeEach(() => {
+    mockOnSubmit.mockClear();
+  });
+
+  it('submits with valid data', async () => {
+    const user = userEvent.setup();
+    render(<LoginForm onSubmit={mockOnSubmit} />);
+
+    await user.type(screen.getByLabelText(/email/i), 'user@example.com');
+    await user.type(screen.getByLabelText(/password/i), 'password123');
+    await user.click(screen.getByRole('button', { name: /sign in/i }));
+
+    await waitFor(() => {
+      expect(mockOnSubmit).toHaveBeenCalledWith({
+        email: 'user@example.com',
+        password: 'password123',
+      });
+    });
+  });
+
+  it('shows validation errors for empty fields', async () => {
+    const user = userEvent.setup();
+    render(<LoginForm onSubmit={mockOnSubmit} />);
+
+    await user.click(screen.getByRole('button', { name: /sign in/i }));
+
+    await waitFor(() => {
+      expect(screen.getByText(/email is required/i)).toBeInTheDocument();
+      expect(screen.getByText(/password is required/i)).toBeInTheDocument();
+    });
+
+    expect(mockOnSubmit).not.toHaveBeenCalled();
+  });
+
+  it('shows error for invalid email', async () => {
+    const user = userEvent.setup();
+    render(<LoginForm onSubmit={mockOnSubmit} />);
+
+    await user.type(screen.getByLabelText(/email/i), 'invalid-email');
+    await user.type(screen.getByLabelText(/password/i), 'password123');
+    await user.click(screen.getByRole('button', { name: /sign in/i }));
+
+    await waitFor(() => {
+      expect(screen.getByText(/invalid email/i)).toBeInTheDocument();
+    });
+  });
+});
+```
+
+### Mocking
+
+```typescript
+// Mocking modules
+vi.mock('@/lib/prisma', () => ({
+  prisma: {
+    user: {
+      findUnique: vi.fn(),
+      create: vi.fn(),
+      update: vi.fn(),
+    },
+  },
+}));
+
+// Mocking fetch
+beforeEach(() => {
+  global.fetch = vi.fn();
+});
+
+it('fetches user data', async () => {
+  (global.fetch as Mock).mockResolvedValueOnce({
+    ok: true,
+    json: async () => ({ id: '1', name: 'Test User' }),
+  });
+
+  const user = await fetchUser('1');
+  expect(user.name).toBe('Test User');
+});
+
+// Mocking timers
+it('debounces search', async () => {
+  vi.useFakeTimers();
+  const onSearch = vi.fn();
+  const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
+
+  render(<SearchInput onSearch={onSearch} debounceMs={300} />);
+
+  await user.type(screen.getByRole('textbox'), 'test');
+
+  expect(onSearch).not.toHaveBeenCalled();
+
+  vi.advanceTimersByTime(300);
+
+  expect(onSearch).toHaveBeenCalledWith('test');
+
+  vi.useRealTimers();
+});
+```
+
+### API Route Testing
+
+```typescript
+// app/api/users/route.test.ts
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { GET, POST } from './route';
+import { prisma } from '@/lib/prisma';
+
+vi.mock('@/lib/prisma');
+vi.mock('@clerk/nextjs/server', () => ({
+  auth: vi.fn(() => ({ userId: 'user_123' })),
+}));
+
+describe('GET /api/users', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns paginated users', async () => {
+    const mockUsers = [
+      { id: '1', name: 'User 1' },
+      { id: '2', name: 'User 2' },
+    ];
+
+    (prisma.user.findMany as Mock).mockResolvedValue(mockUsers);
+    (prisma.user.count as Mock).mockResolvedValue(2);
+
+    const request = new Request('http://localhost/api/users?page=1&limit=10');
+    const response = await GET(request);
+    const data = await response.json();
+
+    expect(data.data).toHaveLength(2);
+    expect(data.pagination.total).toBe(2);
+  });
+});
+
+describe('POST /api/users', () => {
+  it('creates a user with valid data', async () => {
+    const newUser = { id: '1', email: 'new@example.com', name: 'New User' };
+    (prisma.user.create as Mock).mockResolvedValue(newUser);
+
+    const request = new Request('http://localhost/api/users', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email: 'new@example.com', name: 'New User' }),
+    });
+
+    const response = await POST(request);
+    expect(response.status).toBe(201);
+
+    const data = await response.json();
+    expect(data.email).toBe('new@example.com');
+  });
+
+  it('returns 400 for invalid data', async () => {
+    const request = new Request('http://localhost/api/users', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email: 'invalid' }),
+    });
+
+    const response = await POST(request);
+    expect(response.status).toBe(400);
+  });
+});
+```
+
+### E2E Testing with Playwright
+
+```typescript
+// e2e/auth.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Authentication', () => {
+  test('user can sign in', async ({ page }) => {
+    await page.goto('/sign-in');
+
+    await page.fill('[name="email"]', 'test@example.com');
+    await page.fill('[name="password"]', 'password123');
+    await page.click('button[type="submit"]');
+
+    await expect(page).toHaveURL('/dashboard');
+    await expect(page.locator('text=Welcome')).toBeVisible();
+  });
+
+  test('shows error for invalid credentials', async ({ page }) => {
+    await page.goto('/sign-in');
+
+    await page.fill('[name="email"]', 'test@example.com');
+    await page.fill('[name="password"]', 'wrongpassword');
+    await page.click('button[type="submit"]');
+
+    await expect(page.locator('text=Invalid credentials')).toBeVisible();
+  });
+
+  test('redirects unauthenticated users', async ({ page }) => {
+    await page.goto('/dashboard');
+    await expect(page).toHaveURL('/sign-in');
+  });
+});
+
+// e2e/checkout.spec.ts
+test.describe('Checkout', () => {
+  test.beforeEach(async ({ page }) => {
+    // Login before each test
+    await page.goto('/sign-in');
+    await page.fill('[name="email"]', 'test@example.com');
+    await page.fill('[name="password"]', 'password123');
+    await page.click('button[type="submit"]');
+    await page.waitForURL('/dashboard');
+  });
+
+  test('completes checkout flow', async ({ page }) => {
+    // Add item to cart
+    await page.goto('/products');
+    await page.click('text=Add to Cart');
+
+    // Go to checkout
+    await page.click('text=Checkout');
+    await expect(page).toHaveURL('/checkout');
+
+    // Fill shipping info
+    await page.fill('[name="address"]', '123 Test St');
+    await page.fill('[name="city"]', 'Test City');
+    await page.fill('[name="zip"]', '12345');
+
+    // Complete order
+    await page.click('text=Place Order');
+
+    await expect(page.locator('text=Order Confirmed')).toBeVisible();
+  });
+});
+```
+
+### Test Coverage
+
+```bash
+# Run tests with coverage
+npm run test:coverage
+
+# Coverage thresholds in vitest.config.ts
+coverage: {
+  thresholds: {
+    global: {
+      branches: 80,
+      functions: 80,
+      lines: 80,
+      statements: 80,
+    },
+  },
+}
+```
+
+## Testing Checklist
+
+- [ ] Unit tests for utility functions
+- [ ] Component tests for UI components
+- [ ] Integration tests for forms
+- [ ] API route tests
+- [ ] E2E tests for critical paths
+- [ ] Mocks properly isolated
+- [ ] Tests are independent
+- [ ] Coverage meets thresholds
+- [ ] CI runs tests on every PR
+- [ ] Flaky tests addressed
+
+## Trigger Keywords
+test, spec, vitest, jest, playwright, coverage, mock, unit test, integration test, e2e, testing library, expect, describe, it, assertion, fixture