create-kuckit-app 2.0.2 → 2.1.0

package/templates/base/docs/TESTING.md

@@ -0,0 +1,579 @@
+# Testing Guide
+
+This guide covers testing strategies for Kuckit applications, from unit tests to integration testing.
+
+> **Module Testing**: For testing standalone npm modules before publishing, see [Module Testing Guide](./MODULE_TESTING.md).
+
+## Quick Reference
+
+```bash
+# Run all tests
+bun test
+
+# Run tests in a specific package
+bun test --cwd packages/my-module
+
+# Run with coverage
+bun test --coverage
+
+# Watch mode
+bun test --watch
+```
+
+---
+
+## Testing Philosophy
+
+Kuckit follows Clean Architecture, which naturally creates testable boundaries:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        API Layer                            │  ← Integration tests
+│  (oRPC routers, Express handlers)                           │
+├─────────────────────────────────────────────────────────────┤
+│                    Application Layer                         │  ← Unit tests (use cases)
+│  (Use cases, application services)                          │
+├─────────────────────────────────────────────────────────────┤
+│                      Domain Layer                            │  ← Unit tests (pure logic)
+│  (Entities, value objects, domain services)                 │
+├─────────────────────────────────────────────────────────────┤
+│                   Infrastructure Layer                       │  ← Integration tests
+│  (Repositories, external services)                          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Test Pyramid
+
+| Level       | Focus                     | Speed  | Coverage |
+| ----------- | ------------------------- | ------ | -------- |
+| Unit        | Domain logic, use cases   | Fast   | High     |
+| Integration | Repository, API endpoints | Medium | Medium   |
+| E2E         | Full user flows           | Slow   | Low      |
+
+---
+
+## Unit Testing
+
+### Domain Layer Tests
+
+Domain entities contain pure business logic and are the easiest to test:
+
+```typescript
+// packages/my-module/src/server/domain/entities/invoice.test.ts
+import { describe, expect, it } from 'bun:test'
+import { Invoice } from './invoice'
+
+describe('Invoice', () => {
+	it('calculates total from line items', () => {
+		const invoice = Invoice.create({
+			lineItems: [
+				{ description: 'Item 1', amount: 100 },
+				{ description: 'Item 2', amount: 50 },
+			],
+		})
+
+		expect(invoice.total).toBe(150)
+	})
+
+	it('applies discount correctly', () => {
+		const invoice = Invoice.create({
+			lineItems: [{ description: 'Item', amount: 100 }],
+			discountPercent: 10,
+		})
+
+		expect(invoice.total).toBe(90)
+	})
+
+	it('throws on negative amounts', () => {
+		expect(() =>
+			Invoice.create({
+				lineItems: [{ description: 'Item', amount: -50 }],
+			})
+		).toThrow('Amount must be positive')
+	})
+})
+```
+
+### Use Case Tests
+
+Use cases orchestrate domain logic and interact with ports. Mock the ports:
+
+```typescript
+// packages/my-module/src/server/usecases/create-invoice.test.ts
+import { describe, expect, it, mock } from 'bun:test'
+import { CreateInvoiceUseCase } from './create-invoice'
+import type { InvoiceRepository } from '../ports/invoice-repository'
+import type { Logger } from '@kuckit/domain'
+
+describe('CreateInvoiceUseCase', () => {
+	it('creates invoice and persists it', async () => {
+		const mockRepo: InvoiceRepository = {
+			save: mock(() => Promise.resolve()),
+			findById: mock(() => Promise.resolve(null)),
+			findAll: mock(() => Promise.resolve([])),
+		}
+
+		const mockLogger: Logger = {
+			info: mock(() => {}),
+			warn: mock(() => {}),
+			error: mock(() => {}),
+			debug: mock(() => {}),
+		}
+
+		const useCase = new CreateInvoiceUseCase(mockRepo, mockLogger)
+
+		const result = await useCase.execute({
+			customerId: 'cust-123',
+			lineItems: [{ description: 'Service', amount: 500 }],
+		})
+
+		expect(result.total).toBe(500)
+		expect(mockRepo.save).toHaveBeenCalledTimes(1)
+		expect(mockLogger.info).toHaveBeenCalled()
+	})
+
+	it('throws when customer not found', async () => {
+		const mockRepo: InvoiceRepository = {
+			save: mock(() => Promise.reject(new Error('Customer not found'))),
+			findById: mock(() => Promise.resolve(null)),
+			findAll: mock(() => Promise.resolve([])),
+		}
+
+		const useCase = new CreateInvoiceUseCase(mockRepo, {
+			info: () => {},
+			warn: () => {},
+			error: () => {},
+			debug: () => {},
+		})
+
+		await expect(useCase.execute({ customerId: 'invalid', lineItems: [] })).rejects.toThrow(
+			'Customer not found'
+		)
+	})
+})
+```
+
+### Testing with DI Container
+
+When you need the full container for tests:
+
+```typescript
+// packages/my-module/src/server/__tests__/integration.test.ts
+import { describe, expect, it, beforeAll, afterAll } from 'bun:test'
+import { createContainer, asFunction, asValue } from 'awilix'
+import { createTestDatabase } from '../test-utils/database'
+
+describe('Module Integration', () => {
+	let container: ReturnType<typeof createContainer>
+	let testDb: Awaited<ReturnType<typeof createTestDatabase>>
+
+	beforeAll(async () => {
+		testDb = await createTestDatabase()
+
+		container = createContainer()
+		container.register({
+			db: asValue(testDb.db),
+			logger: asValue({ info: () => {}, warn: () => {}, error: () => {}, debug: () => {} }),
+			invoiceRepository: asFunction(({ db }) => new DrizzleInvoiceRepository(db)).scoped(),
+			createInvoiceUseCase: asFunction(
+				({ invoiceRepository, logger }) => new CreateInvoiceUseCase(invoiceRepository, logger)
+			).scoped(),
+		})
+	})
+
+	afterAll(async () => {
+		await testDb.cleanup()
+	})
+
+	it('creates invoice through use case', async () => {
+		const useCase = container.resolve('createInvoiceUseCase')
+		const result = await useCase.execute({
+			customerId: 'test-customer',
+			lineItems: [{ description: 'Test', amount: 100 }],
+		})
+
+		expect(result.id).toBeDefined()
+	})
+})
+```
+
+---
+
+## Integration Testing
+
+### Repository Tests
+
+Test repositories against a real database:
+
+```typescript
+// packages/my-module/src/server/adapters/__tests__/invoice-repository.test.ts
+import { describe, expect, it, beforeAll, afterAll, beforeEach } from 'bun:test'
+import { DrizzleInvoiceRepository } from '../invoice-repository'
+import { createTestDatabase, cleanupTestData } from '../../test-utils/database'
+
+describe('DrizzleInvoiceRepository', () => {
+	let repository: DrizzleInvoiceRepository
+	let testDb: Awaited<ReturnType<typeof createTestDatabase>>
+
+	beforeAll(async () => {
+		testDb = await createTestDatabase()
+		repository = new DrizzleInvoiceRepository(testDb.db)
+	})
+
+	afterAll(async () => {
+		await testDb.cleanup()
+	})
+
+	beforeEach(async () => {
+		await cleanupTestData(testDb.db)
+	})
+
+	it('saves and retrieves invoice', async () => {
+		const invoice = Invoice.create({
+			customerId: 'cust-123',
+			lineItems: [{ description: 'Test', amount: 100 }],
+		})
+
+		await repository.save(invoice)
+
+		const retrieved = await repository.findById(invoice.id)
+		expect(retrieved).toBeDefined()
+		expect(retrieved?.total).toBe(100)
+	})
+
+	it('returns null for non-existent invoice', async () => {
+		const result = await repository.findById('non-existent-id')
+		expect(result).toBeNull()
+	})
+})
+```
+
+### Test Database Utilities
+
+Create a reusable test database helper:
+
+```typescript
+// packages/my-module/src/server/test-utils/database.ts
+import { drizzle } from 'drizzle-orm/node-postgres'
+import { Pool } from 'pg'
+import * as schema from '../adapters/schema'
+
+export async function createTestDatabase() {
+	const testDbUrl =
+		process.env.TEST_DATABASE_URL ?? 'postgresql://postgres:postgres@localhost:5432/kuckit_test'
+
+	const pool = new Pool({ connectionString: testDbUrl })
+	const db = drizzle(pool, { schema })
+
+	return {
+		db,
+		pool,
+		cleanup: async () => {
+			await pool.end()
+		},
+	}
+}
+
+export async function cleanupTestData(db: ReturnType<typeof drizzle>) {
+	await db.delete(schema.invoices)
+	await db.delete(schema.lineItems)
+}
+```
+
+### API Endpoint Tests
+
+Test oRPC routers with a test client:
+
+```typescript
+// packages/my-module/src/server/api/__tests__/invoices-router.test.ts
+import { describe, expect, it, beforeAll, afterAll } from 'bun:test'
+import { createORPCFetchClient } from '@orpc/client'
+import type { InvoicesRouter } from '../invoices-router'
+
+describe('Invoices API', () => {
+	let client: ReturnType<typeof createORPCFetchClient<InvoicesRouter>>
+	let server: any
+
+	beforeAll(async () => {
+		// Start test server
+		server = await startTestServer()
+		client = createORPCFetchClient<InvoicesRouter>({
+			baseURL: `http://localhost:${server.port}/rpc/invoices`,
+		})
+	})
+
+	afterAll(async () => {
+		await server.close()
+	})
+
+	it('creates invoice via API', async () => {
+		const result = await client.create({
+			customerId: 'cust-123',
+			lineItems: [{ description: 'API Test', amount: 250 }],
+		})
+
+		expect(result.id).toBeDefined()
+		expect(result.total).toBe(250)
+	})
+
+	it('returns 404 for non-existent invoice', async () => {
+		await expect(client.getById({ id: 'non-existent' })).rejects.toThrow(/not found/i)
+	})
+})
+```
+
+---
+
+## Test Configuration
+
+### Bun Test Setup
+
+Create `bunfig.toml` in your project root:
+
+```toml
+[test]
+preload = ["./test-setup.ts"]
+```
+
+Create `test-setup.ts` for global setup:
+
+```typescript
+// test-setup.ts
+import { beforeAll, afterAll } from 'bun:test'
+
+beforeAll(async () => {
+	// Global setup: start containers, seed data, etc.
+	console.log('🧪 Starting test suite...')
+})
+
+afterAll(async () => {
+	// Global cleanup
+	console.log('✅ Test suite complete')
+})
+```
+
+### Environment Variables for Tests
+
+Create `.env.test`:
+
+```bash
+# Test database (separate from dev)
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/kuckit_test
+TEST_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/kuckit_test
+
+# Auth (test values)
+BETTER_AUTH_SECRET=test-secret-for-testing-only
+BETTER_AUTH_URL=http://localhost:3000
+
+# Disable external services in tests
+DISABLE_EXTERNAL_APIS=true
+```
+
+Load in tests:
+
+```typescript
+import { beforeAll } from 'bun:test'
+
+beforeAll(() => {
+	// Load test environment
+	process.loadEnvFile('.env.test')
+})
+```
+
+---
+
+## Test Patterns
+
+### Factories for Test Data
+
+Create factories to generate test data:
+
+```typescript
+// packages/my-module/src/server/test-utils/factories.ts
+import { Invoice } from '../domain/entities/invoice'
+
+let invoiceCounter = 0
+
+export function createTestInvoice(overrides: Partial<InvoiceProps> = {}): Invoice {
+	invoiceCounter++
+	return Invoice.create({
+		id: `test-invoice-${invoiceCounter}`,
+		customerId: `test-customer-${invoiceCounter}`,
+		lineItems: [{ description: 'Test Item', amount: 100 }],
+		...overrides,
+	})
+}
+
+export function createTestLineItem(overrides: Partial<LineItemProps> = {}) {
+	return {
+		description: 'Test Line Item',
+		amount: 100,
+		quantity: 1,
+		...overrides,
+	}
+}
+```
+
+### Snapshot Testing
+
+Use snapshots for complex outputs:
+
+```typescript
+import { describe, expect, it } from 'bun:test'
+
+describe('Invoice formatting', () => {
+	it('formats invoice as JSON', () => {
+		const invoice = createTestInvoice({
+			lineItems: [
+				{ description: 'Service A', amount: 100 },
+				{ description: 'Service B', amount: 200 },
+			],
+		})
+
+		expect(invoice.toJSON()).toMatchSnapshot()
+	})
+})
+```
+
+### Testing Async Operations
+
+```typescript
+import { describe, expect, it } from 'bun:test'
+
+describe('Async operations', () => {
+	it('handles timeout correctly', async () => {
+		const slowOperation = new Promise((resolve) => setTimeout(() => resolve('done'), 100))
+
+		const result = await slowOperation
+		expect(result).toBe('done')
+	})
+
+	it('rejects on error', async () => {
+		const failingOperation = Promise.reject(new Error('Failed'))
+
+		await expect(failingOperation).rejects.toThrow('Failed')
+	})
+})
+```
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions Workflow
+
+```yaml
+# .github/workflows/test.yml
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:15
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: kuckit_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Run type checks
+        run: bun run check-types
+
+      - name: Run tests
+        run: bun test --coverage
+        env:
+          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/kuckit_test
+          BETTER_AUTH_SECRET: test-secret
+          BETTER_AUTH_URL: http://localhost:3000
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage/coverage.json
+```
+
+### Pre-commit Hooks
+
+Add to `.husky/pre-commit`:
+
+```bash
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+bun run check-types
+bun test --bail
+```
+
+---
+
+## Debugging Tests
+
+### Verbose Output
+
+```bash
+# Run with verbose logging
+bun test --verbose
+
+# Run single test file
+bun test packages/my-module/src/server/usecases/create-invoice.test.ts
+```
+
+### Debug Mode
+
+```typescript
+import { describe, it } from 'bun:test'
+
+describe('Debugging', () => {
+	it('logs intermediate values', async () => {
+		const result = await someOperation()
+
+		// Debug output
+		console.log('Result:', JSON.stringify(result, null, 2))
+
+		expect(result).toBeDefined()
+	})
+})
+```
+
+### Inspecting Test Database
+
+```bash
+# Connect to test database
+psql postgresql://postgres:postgres@localhost:5432/kuckit_test
+
+# Check table contents
+SELECT * FROM invoices LIMIT 10;
+```
+
+---
+
+## Related Documentation
+
+- [Module Testing Guide](./MODULE_TESTING.md) - Testing modules before npm publish
+- [Module Development](../packages/sdk/docs/MODULE_DEVELOPMENT.md) - Building modules
+- [Architecture Overview](./ARCHITECTURE.md) - Clean Architecture layers
+- [Troubleshooting](./TROUBLESHOOTING.md) - Common issues and fixes