From 5822ceb7c4325c2db17a5d3728904de04a1903bf Mon Sep 17 00:00:00 2001
From: Damjan Savic <info@damjan-savic.com>
Date: Sun, 25 Jan 2026 06:34:13 +0100
Subject: [PATCH] auto-claude: subtask-1-3 - Document testing requirements and
 setup

---
 CONTRIBUTING.md | 131 +++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 119 insertions(+), 12 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 48b62e4..a733bb0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -372,34 +372,141 @@ export function WelcomeMessage() {
 
 ## Testing
 
-### Unit Tests
-- Write tests for utility functions and complex logic
-- Use Vitest as the testing framework
-- Place test files next to the code they test with `.test.ts` or `.test.tsx` extension
+This project uses **Vitest** as its testing framework. Vitest is a fast, modern test runner built for Vite-based projects, offering:
+- Lightning-fast execution with native ESM support
+- Jest-compatible API for easy migration and familiarity
+- First-class TypeScript support
+- Built-in coverage reporting with c8
+
+**Current State:** The project is fully configured with Vitest, but **no tests currently exist**. We encourage contributors to add tests for new features and gradually improve test coverage.
+
+### Test Setup
+
+Vitest is already configured in `package.json`:
+```json
+{
+  "scripts": {
+    "test": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "vitest": "^1.3.1"
+  }
+}
+```
+
+### Running Tests
+
+```bash
+# Run tests in watch mode (recommended during development)
+npm test
+
+# Run tests once (useful for CI/CD)
+npm run test:coverage
+
+# The test runner will:
+# - Automatically detect .test.ts, .test.tsx, .spec.ts, .spec.tsx files
+# - Re-run tests when files change (in watch mode)
+# - Display coverage reports (with --coverage flag)
+```
+
+### Writing Tests
+
+When adding tests to this project, follow these conventions:
+
+#### 1. **File Naming & Location**
+- Place test files **next to the code they test**
+- Use `.test.ts` or `.test.tsx` extension for test files
+- Match the filename of the file being tested
+
+Example:
+```
+src/utils/
+├── formatDate.ts          # Source file
+└── formatDate.test.ts     # Test file
+```
+
+#### 2. **Test Structure**
+- Use `describe` blocks to group related tests
+- Use `it` or `test` for individual test cases
+- Write descriptive test names that explain the expected behavior
 
 Example:
 ```typescript
-// formatDate.test.ts
+// src/utils/formatDate.test.ts
 import { describe, it, expect } from 'vitest';
 import { formatDate } from './formatDate';
 
 describe('formatDate', () => {
-  it('formats date correctly', () => {
+  it('formats date in DD.MM.YYYY format', () => {
     const date = new Date('2024-01-15');
     expect(formatDate(date)).toBe('15.01.2024');
   });
+
+  it('handles invalid dates gracefully', () => {
+    const invalidDate = new Date('invalid');
+    expect(formatDate(invalidDate)).toBe('Invalid Date');
+  });
 });
 ```
 
-### Running Tests
-```bash
-# Run tests in watch mode
-npm test
+#### 3. **Component Testing**
+For React components, use Vitest with React Testing Library patterns:
 
-# Run tests once with coverage
-npm run test:coverage
+```typescript
+// src/components/Button.test.tsx
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { Button } from './Button';
+
+describe('Button', () => {
+  it('renders with correct text', () => {
+    render(<Button>Click me</Button>);
+    expect(screen.getByText('Click me')).toBeInTheDocument();
+  });
+});
 ```
 
+#### 4. **What to Test**
+- **Utility functions** - Pure functions and helpers
+- **Business logic** - Complex calculations and transformations
+- **Hooks** - Custom React hooks with multiple states
+- **Components** - User interactions and rendering logic
+- **API integrations** - Service layer functions (use mocks)
+
+#### 5. **Testing Conventions**
+- **Arrange-Act-Assert** pattern for test structure
+- **One assertion per test** when possible (for clarity)
+- **Mock external dependencies** (API calls, database, etc.)
+- **Test edge cases** and error conditions
+- **Use meaningful test data** that reflects real usage
+
+Example:
+```typescript
+describe('calculateDiscount', () => {
+  it('applies 10% discount for orders over $100', () => {
+    // Arrange
+    const orderTotal = 150;
+    const discountThreshold = 100;
+
+    // Act
+    const result = calculateDiscount(orderTotal, discountThreshold);
+
+    // Assert
+    expect(result).toBe(135); // 150 - 15 (10%)
+  });
+});
+```
+
+### Test Coverage Goals
+
+While we don't enforce strict coverage requirements, aim for:
+- **80%+ coverage** for utility functions and business logic
+- **60%+ coverage** for components
+- **100% coverage** for critical paths (authentication, payments, data validation)
+
+Run `npm run test:coverage` to see current coverage reports.
+
 ## Commit Guidelines
 
 ### Commit Message Format