@nextsparkjs/ai-workflow 0.1.0-beta.100

package/claude/skills/jest-unit/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: jest-unit
+description: |
+  Jest unit testing patterns for this Next.js application.
+  Covers test structure, mocking strategies, React component testing, hook testing, and coverage targets.
+  Use this skill when writing unit tests for services, hooks, utilities, or components.
+allowed-tools: Read, Glob, Grep
+version: 1.1.0
+---
+
+# Jest Unit Testing Skill
+
+Patterns for writing effective unit tests with Jest and React Testing Library.
+
+## Architecture Overview
+
+```
+TEST FILE STRUCTURE:
+
+core/tests/jest/
+├── api/                 # API route tests
+├── hooks/               # React hooks tests
+├── lib/                 # Utility tests
+├── components/          # Component tests
+├── services/            # Service tests
+├── __mocks__/           # Mock utilities
+│   ├── db-mocks.ts
+│   ├── better-auth.js
+│   └── next-server.js
+└── setup.ts             # Global configuration
+
+contents/themes/default/tests/jest/
+└── ...                  # Theme-specific tests
+
+contents/plugins/*/__tests__/
+└── ...                  # Plugin-specific tests
+```
+
+## When to Use This Skill
+
+- Writing unit tests for services
+- Testing React hooks
+- Testing React components
+- Mocking database operations
+- Setting up test coverage
+
+---
+
+## Test File Structure
+
+### Naming Conventions
+
+```
+*.test.ts   - TypeScript unit tests
+*.test.tsx  - React component tests
+```
+
+### Standard Test Structure
+
+```typescript
+import { describe, test, expect, beforeEach, afterEach, jest } from '@jest/globals'
+import { functionToTest } from '@/core/lib/module'
+
+describe('ModuleName', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  afterEach(() => {
+    jest.clearAllMocks()
+    jest.resetModules()
+  })
+
+  describe('Feature Group', () => {
+    test('should do expected behavior when condition met', () => {
+      // Arrange
+      const input = 'test-data'
+
+      // Act
+      const result = functionToTest(input)
+
+      // Assert
+      expect(result).toBe('expected-output')
+    })
+  })
+})
+```
+
+---
+
+## Jest Configuration
+
+```typescript
+// jest.config.ts
+import type { Config } from 'jest'
+
+export const baseConfig: Partial<Config> = {
+  preset: 'ts-jest',
+  testEnvironment: 'jsdom',
+
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/$1',
+    '^@/core/(.*)$': '<rootDir>/core/$1',
+    'next/server': '<rootDir>/core/tests/jest/__mocks__/next-server.js',
+  },
+
+  setupFilesAfterEnv: ['<rootDir>/core/tests/setup.ts'],
+  testTimeout: 10000,
+}
+```
+
+### Test Scripts
+
+```bash
+pnpm test              # Run all core tests
+pnpm test:theme        # Run theme-specific tests
+pnpm test:coverage     # Generate coverage reports
+pnpm test:watch        # Watch mode
+```
+
+---
+
+## Essential Mocking (Quick Reference)
+
+### Database (MANDATORY)
+
+```typescript
+jest.mock('@/core/lib/db', () => ({
+  queryWithRLS: jest.fn(),
+  queryOneWithRLS: jest.fn(),
+  mutateWithRLS: jest.fn(),
+}))
+
+const mockQueryWithRLS = queryWithRLS as jest.MockedFunction<typeof queryWithRLS>
+
+test('example', async () => {
+  mockQueryWithRLS.mockResolvedValue([{ id: '123' }])
+  // ...
+})
+```
+
+### Next.js Navigation
+
+```typescript
+jest.mock('next/navigation', () => ({
+  useRouter: () => ({ push: jest.fn(), replace: jest.fn() }),
+  usePathname: () => '/',
+  useSearchParams: () => new URLSearchParams(),
+}))
+```
+
+### Translations
+
+```typescript
+jest.mock('next-intl', () => ({
+  useTranslations: () => (key: string) => key,
+  useLocale: () => 'en',
+}))
+```
+
+→ See `references/mocking-patterns.md` for complete mocking strategies
+
+---
+
+## Quick Testing Patterns
+
+### Component Test
+
+```typescript
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+test('form submission', async () => {
+  const user = userEvent.setup()
+  render(<MyForm />)
+
+  await user.type(screen.getByLabelText('Email'), 'test@example.com')
+  await user.click(screen.getByRole('button', { name: /submit/i }))
+
+  expect(await screen.findByText('Success')).toBeInTheDocument()
+})
+```
+
+→ See `references/component-testing.md` for complete patterns
+
+### Hook Test
+
+```typescript
+import { renderHook, act } from '@testing-library/react'
+
+test('hook state update', () => {
+  const { result } = renderHook(() => useCounter())
+
+  act(() => {
+    result.current.increment()
+  })
+
+  expect(result.current.count).toBe(1)
+})
+```
+
+→ See `references/service-hook-testing.md` for complete patterns
+
+---
+
+## Coverage Targets
+
+| Category | Target | Notes |
+|----------|--------|-------|
+| **Critical Paths** | 90%+ | Auth, API, Validation |
+| **Features** | 80%+ | UI, Business Logic |
+| **Utilities** | 80%+ | Helpers, Services |
+| **Components** | 70%+ | UI Components |
+
+---
+
+## Common Assertions
+
+```typescript
+// Equality
+expect(result).toBe('expected')
+expect(result).toEqual({ id: '123' })
+
+// Truthiness
+expect(result).toBeTruthy()
+expect(result).toBeNull()
+expect(result).toBeDefined()
+
+// Collections
+expect(array).toHaveLength(2)
+expect(array).toContain('item')
+expect(obj).toHaveProperty('key')
+
+// DOM (Testing Library)
+expect(element).toBeInTheDocument()
+expect(element).toHaveClass('className')
+expect(element).toBeVisible()
+expect(element).toBeDisabled()
+
+// Mocks
+expect(mockFn).toHaveBeenCalled()
+expect(mockFn).toHaveBeenCalledWith('arg')
+expect(mockFn).toHaveBeenCalledTimes(1)
+```
+
+---
+
+## Anti-Patterns
+
+```typescript
+// ❌ NEVER: Test implementation details
+expect(result.current._internalState).toBe('value')
+
+// ✅ CORRECT: Test observable behavior
+expect(result.current.displayValue).toBe('value')
+
+// ❌ NEVER: Skip cleanup
+// No afterEach → leaks between tests
+
+// ✅ CORRECT: Always cleanup
+afterEach(() => jest.clearAllMocks())
+
+// ❌ NEVER: Async without await
+fetchData().then(data => expect(data).toBeDefined())
+
+// ✅ CORRECT: Properly await
+const data = await fetchData()
+expect(data).toBeDefined()
+
+// ❌ NEVER: Use fireEvent for user actions
+fireEvent.change(input, { target: { value: 'text' } })
+
+// ✅ CORRECT: Use userEvent
+await user.type(input, 'text')
+```
+
+---
+
+## Checklist
+
+Before finalizing unit tests:
+
+- [ ] All database calls mocked (queryWithRLS, mutateWithRLS)
+- [ ] External APIs mocked (fetch)
+- [ ] Next.js functions mocked (useRouter, useSearchParams)
+- [ ] afterEach cleanup with jest.clearAllMocks()
+- [ ] Async tests properly awaited
+- [ ] Test both success and error paths
+- [ ] Edge cases covered (null, empty, invalid input)
+- [ ] Coverage targets met (90%+ critical, 80%+ features)
+- [ ] Test names are descriptive
+
+---
+
+## References
+
+- `references/mocking-patterns.md` - Complete mocking strategies
+- `references/component-testing.md` - React component testing patterns
+- `references/service-hook-testing.md` - Service and hook testing patterns
+
+## Related Skills
+
+- `cypress-e2e` - Integration/E2E testing
+- `cypress-api` - API testing with Cypress
+- `zod-validation` - Schema validation testing
+- `service-layer` - Service patterns to test

package/claude/skills/jest-unit/references/component-testing.md

@@ -0,0 +1,371 @@
+# Component Testing Reference
+
+React component testing patterns with Testing Library and Jest.
+
+## Basic Component Test Structure
+
+```typescript
+import { describe, test, expect, beforeEach, jest } from '@jest/globals'
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { LoginForm } from '@/core/components/auth/forms/LoginForm'
+
+describe('LoginForm Component', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  describe('Rendering', () => {
+    test('should render login form with all essential elements', () => {
+      render(<LoginForm />)
+
+      expect(screen.getByText('Sign In')).toBeInTheDocument()
+      expect(screen.getByLabelText('Email')).toBeInTheDocument()
+      expect(screen.getByLabelText('Password')).toBeInTheDocument()
+      expect(screen.getByRole('button', { name: /sign in/i })).toBeInTheDocument()
+    })
+  })
+
+  describe('User Interactions', () => {
+    test('should call signIn with correct credentials', async () => {
+      const user = userEvent.setup()
+
+      render(<LoginForm />)
+
+      await user.type(screen.getByLabelText('Email'), 'test@example.com')
+      await user.type(screen.getByLabelText('Password'), 'password123')
+      await user.click(screen.getByRole('button', { name: /sign in/i }))
+
+      await waitFor(() => {
+        expect(mockSignIn).toHaveBeenCalledWith({
+          email: 'test@example.com',
+          password: 'password123'
+        })
+      })
+    })
+  })
+
+  describe('Error Handling', () => {
+    test('should display error message on failed login', async () => {
+      const user = userEvent.setup()
+      mockSignIn.mockRejectedValue(new Error('Invalid credentials'))
+
+      render(<LoginForm />)
+
+      await user.type(screen.getByLabelText('Email'), 'test@example.com')
+      await user.type(screen.getByLabelText('Password'), 'wrong')
+      await user.click(screen.getByRole('button', { name: /sign in/i }))
+
+      await waitFor(() => {
+        expect(screen.getByText(/invalid credentials/i)).toBeInTheDocument()
+      })
+    })
+  })
+
+  describe('Accessibility', () => {
+    test('should have proper accessibility attributes', () => {
+      render(<LoginForm />)
+
+      const emailInput = screen.getByLabelText('Email')
+      expect(emailInput).toHaveAttribute('type', 'email')
+      expect(emailInput).toHaveAttribute('aria-required', 'true')
+    })
+  })
+})
+```
+
+---
+
+## userEvent vs fireEvent
+
+### userEvent (Preferred)
+
+```typescript
+import userEvent from '@testing-library/user-event'
+
+// ✅ CORRECT - Realistic user interactions
+test('user types in input field', async () => {
+  const user = userEvent.setup()
+
+  render(<MyComponent />)
+
+  await user.type(screen.getByRole('textbox'), 'Hello')
+  await user.click(screen.getByRole('button'))
+  await user.keyboard('{Enter}')
+  await user.tab()
+
+  expect(screen.getByText('Hello')).toBeInTheDocument()
+})
+```
+
+### fireEvent (Only for Edge Cases)
+
+```typescript
+// Use fireEvent only when userEvent doesn't work
+// (e.g., custom events, scroll, resize)
+test('handles scroll event', () => {
+  render(<ScrollComponent />)
+
+  const container = screen.getByTestId('scroll-container')
+  fireEvent.scroll(container, { target: { scrollY: 100 } })
+
+  expect(screen.getByText('Scrolled')).toBeInTheDocument()
+})
+```
+
+---
+
+## Common userEvent Actions
+
+```typescript
+const user = userEvent.setup()
+
+// Typing
+await user.type(input, 'text')           // Type text
+await user.clear(input)                  // Clear input
+await user.type(input, 'text{Enter}')    // Type and submit
+
+// Clicking
+await user.click(element)                // Single click
+await user.dblClick(element)             // Double click
+await user.tripleClick(element)          // Triple click (select all)
+
+// Keyboard
+await user.keyboard('{Enter}')           // Press Enter
+await user.keyboard('{Tab}')             // Press Tab
+await user.keyboard('{Escape}')          // Press Escape
+await user.keyboard('{ArrowDown}')       // Arrow keys
+await user.keyboard('{Shift>}A{/Shift}') // Shift+A
+
+// Selection
+await user.selectOptions(select, 'option-value')
+await user.selectOptions(select, ['opt1', 'opt2'])  // Multi-select
+
+// Hover
+await user.hover(element)
+await user.unhover(element)
+
+// Clipboard
+await user.copy()
+await user.paste()
+await user.cut()
+
+// Focus
+await user.tab()                         // Move focus forward
+await user.tab({ shift: true })          // Move focus backward
+```
+
+---
+
+## Query Priority
+
+Testing Library recommends queries in this priority order:
+
+### 1. Accessible to Everyone (Preferred)
+
+```typescript
+// By Role (best)
+screen.getByRole('button', { name: /submit/i })
+screen.getByRole('textbox', { name: /email/i })
+screen.getByRole('heading', { level: 1 })
+
+// By Label Text
+screen.getByLabelText('Email')
+
+// By Placeholder Text
+screen.getByPlaceholderText('Enter email...')
+
+// By Text Content
+screen.getByText('Submit')
+screen.getByText(/submit/i)  // Case insensitive
+```
+
+### 2. Semantic Queries
+
+```typescript
+screen.getByAltText('Profile photo')
+screen.getByTitle('Close dialog')
+screen.getByDisplayValue('current value')
+```
+
+### 3. Test IDs (Last Resort)
+
+```typescript
+// Only when other queries don't work
+screen.getByTestId('complex-component')
+screen.getByTestId('data-cy-selector')
+```
+
+---
+
+## Async Testing Patterns
+
+### waitFor
+
+```typescript
+test('should show loading then data', async () => {
+  render(<DataComponent />)
+
+  // Initially loading
+  expect(screen.getByText('Loading...')).toBeInTheDocument()
+
+  // Wait for data
+  await waitFor(() => {
+    expect(screen.getByText('Data loaded')).toBeInTheDocument()
+  }, { timeout: 3000 })
+})
+```
+
+### findBy (Combines getBy + waitFor)
+
+```typescript
+test('should load async content', async () => {
+  render(<AsyncComponent />)
+
+  // findBy waits for element to appear
+  const element = await screen.findByText('Loaded content', {}, { timeout: 5000 })
+  expect(element).toBeInTheDocument()
+})
+```
+
+### waitForElementToBeRemoved
+
+```typescript
+test('should hide loading spinner', async () => {
+  render(<DataComponent />)
+
+  await waitForElementToBeRemoved(() => screen.queryByText('Loading...'))
+
+  expect(screen.getByText('Data')).toBeInTheDocument()
+})
+```
+
+---
+
+## Form Testing
+
+### Basic Form
+
+```typescript
+test('submits form with correct data', async () => {
+  const onSubmit = jest.fn()
+  const user = userEvent.setup()
+
+  render(<ContactForm onSubmit={onSubmit} />)
+
+  await user.type(screen.getByLabelText('Name'), 'John Doe')
+  await user.type(screen.getByLabelText('Email'), 'john@example.com')
+  await user.type(screen.getByLabelText('Message'), 'Hello!')
+  await user.click(screen.getByRole('button', { name: /submit/i }))
+
+  expect(onSubmit).toHaveBeenCalledWith({
+    name: 'John Doe',
+    email: 'john@example.com',
+    message: 'Hello!'
+  })
+})
+```
+
+### Form Validation
+
+```typescript
+test('shows validation errors', async () => {
+  const user = userEvent.setup()
+
+  render(<ContactForm />)
+
+  // Submit empty form
+  await user.click(screen.getByRole('button', { name: /submit/i }))
+
+  // Check for validation errors
+  expect(await screen.findByText('Name is required')).toBeInTheDocument()
+  expect(await screen.findByText('Email is required')).toBeInTheDocument()
+})
+```
+
+---
+
+## Testing with Context/Providers
+
+```typescript
+const renderWithProviders = (ui: React.ReactElement, options = {}) => {
+  const AllProviders = ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>
+      <ThemeProvider>
+        <AuthProvider>
+          {children}
+        </AuthProvider>
+      </ThemeProvider>
+    </QueryClientProvider>
+  )
+
+  return render(ui, { wrapper: AllProviders, ...options })
+}
+
+// Usage
+test('renders with all providers', () => {
+  renderWithProviders(<MyComponent />)
+  // ...
+})
+```
+
+---
+
+## Testing Modals/Dialogs
+
+```typescript
+test('opens and closes modal', async () => {
+  const user = userEvent.setup()
+
+  render(<ModalComponent />)
+
+  // Open modal
+  await user.click(screen.getByRole('button', { name: /open/i }))
+
+  // Check modal is visible
+  expect(screen.getByRole('dialog')).toBeInTheDocument()
+
+  // Close modal
+  await user.click(screen.getByRole('button', { name: /close/i }))
+
+  // Check modal is gone
+  await waitFor(() => {
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+  })
+})
+```
+
+---
+
+## Common Assertions (DOM)
+
+```typescript
+// Presence
+expect(element).toBeInTheDocument()
+expect(element).not.toBeInTheDocument()
+
+// Visibility
+expect(element).toBeVisible()
+expect(element).not.toBeVisible()
+
+// State
+expect(element).toBeDisabled()
+expect(element).toBeEnabled()
+expect(element).toBeChecked()
+expect(element).toHaveFocus()
+
+// Content
+expect(element).toHaveTextContent('text')
+expect(element).toHaveTextContent(/regex/i)
+expect(element).toBeEmpty()
+
+// Attributes
+expect(element).toHaveAttribute('href', '/path')
+expect(element).toHaveClass('active')
+expect(element).toHaveStyle({ color: 'red' })
+
+// Form
+expect(input).toHaveValue('value')
+expect(input).toHaveDisplayValue('displayed')
+expect(select).toHaveValue('option-value')
+```