docs: map existing codebase

2026-04-27 09:13:11 +02:00
parent 15dc0d289a
commit 3e91d5713d
7 changed files with 2237 additions and 0 deletions
--- a/.planning/codebase/TESTING.md
+++ b/.planning/codebase/TESTING.md
@@ -0,0 +1,340 @@
+# Testing Patterns
+
+**Analysis Date:** 2026-04-27
+
+## Test Framework Status
+
+**Current State:** **Minimal test coverage - testing infrastructure in place but not actively used**
+
+### Jest (Server)
+
+**Runner:**
+- Jest 30.x
+- Config: Inline in `server/package.json` (lines 88-104)
+
+**Run Commands:**
+```bash
+cd server
+npm test              # Run all unit tests (seeks *.spec.ts files)
+npm run test:watch   # Watch mode for development
+npm run test:cov     # Generate coverage report
+npm run test:debug   # Debug mode with breakpoints
+npm run test:e2e     # Run end-to-end tests (config: test/jest-e2e.json)
+```
+
+**Configuration Details:**
+```json
+{
+  "moduleFileExtensions": ["js", "json", "ts"],
+  "rootDir": "src",
+  "testRegex": ".*\\.spec\\.ts$",
+  "transform": { "^.+\\.(t|j)s$": "ts-jest" },
+  "collectCoverageFrom": ["**/*.(t|j)s"],
+  "coverageDirectory": "../coverage",
+  "testEnvironment": "node"
+}
+```
+
+**Testing Libraries:**
+- Jest 30.x (test runner)
+- ts-jest (TypeScript support)
+- @nestjs/testing (NestJS module testing utilities)
+- supertest (HTTP request testing)
+
+### Vitest (Client)
+
+**Status:** Not installed. No vitest config present in `client/package.json`
+
+**Implications:** Client has zero automated test infrastructure. Any future testing would require adding vitest and configuring it.
+
+## Test File Organization
+
+**Server:**
+- Location: Unit tests alongside source in `src/`, E2E tests in `test/`
+- Naming: `*.spec.ts` for unit tests, `*.e2e-spec.ts` for integration tests
+- Example: No unit test files currently exist in `server/src/`
+
+**Current Test Suite:**
+- Location: `server/test/app.e2e-spec.ts`
+- Scope: Single basic integration test for app startup
+- Status: Placeholder test (checks 'Hello World!' endpoint that doesn't exist)
+
+**Client:**
+- No test files present
+- No test directory structure
+
+## Test Structure (Server)
+
+**E2E Test Example** (`server/test/app.e2e-spec.ts`):
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+import { INestApplication } from '@nestjs/common';
+import request from 'supertest';
+import { AppModule } from './../src/app.module';
+
+describe('AppController (e2e)', () => {
+  let app: INestApplication;
+
+  beforeEach(async () => {
+    const moduleFixture: TestingModule = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = moduleFixture.createNestApplication();
+    await app.init();
+  });
+
+  it('/ (GET)', () => {
+    return request(app.getHttpServer())
+      .get('/')
+      .expect(200)
+      .expect('Hello World!');
+  });
+});
+```
+
+**Patterns:**
+- `describe()` for test suites
+- `it()` for individual tests (or `test()`)
+- `beforeEach()` for setup (module initialization)
+- Async/await for async operations
+- Chained `.expect()` assertions with supertest
+
+## Mocking
+
+### Server (Jest/NestJS)
+
+**Framework:** @nestjs/testing provides test module builder
+
+**Pattern Observed:**
+```typescript
+const moduleFixture: TestingModule = await Test.createTestingModule({
+  imports: [AppModule],  // Or specific module imports
+}).compile();
+
+const service = moduleFixture.get<ServiceName>(ServiceName);
+```
+
+**What to Mock:**
+- Database (Prisma) - would use mock provider
+- External APIs - would use jest.mock()
+- Services with dependencies - inject via module builder
+
+**What NOT to Mock:**
+- NestJS core decorators
+- Guards/Middleware (test through integration)
+- Database schema (use test database)
+
+### Client
+
+**No mocking patterns established yet** - testing infrastructure not present.
+
+Would require:
+- Vitest for runner
+- `@testing-library/react` for component testing
+- Mock fetch/axios calls
+- Mock WebSocket connections
+
+## Fixtures and Factories
+
+**Server:**
+
+**Test Data Approach:** Not fully established, but patterns available:
+- Prisma seed scripts exist in `server/prisma/`:
+  - `seed.ts` - Basic seed
+  - `seed-equipment.ts` - 5,482 equipment items
+  - `seed-feats.ts` - Feat database
+- Could be reused for test fixtures
+
+**Location:** Would be in test directory or integrated with jest setup
+
+**No factory pattern observed** - tests would need to build objects inline or create helper functions
+
+**Client:**
+
+**Not applicable** - no test infrastructure
+
+## Coverage
+
+**Requirements:** None enforced (no CI/CD pipeline checking coverage)
+
+**View Coverage:**
+```bash
+cd server
+npm run test:cov
+# Generates: server/coverage/
+```
+
+**Current Coverage:** Unknown (no tests running)
+
+**Gaps:** **Entire codebase untested**
+- Auth module: No unit tests (`server/src/modules/auth/`)
+- Characters module: No unit tests (`server/src/modules/characters/`)
+- Battle module: No unit tests (`server/src/modules/battle/`)
+- WebSocket gateway: No tests
+- Guards/Decorators: No tests
+- Client components: No tests
+- Client hooks: No tests
+- State management (Zustand): No tests
+
+## Test Types
+
+### Unit Tests
+
+**Not currently used**
+
+**When implemented, pattern would be:**
+- Test individual services in isolation
+- Mock Prisma client
+- Location: `server/src/modules/[module]/[module].service.spec.ts`
+- Example test structure (not yet used):
+```typescript
+describe('AuthService', () => {
+  let service: AuthService;
+  let prisma: PrismaService;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      providers: [AuthService, { provide: PrismaService, useValue: mockPrisma }],
+    }).compile();
+
+    service = module.get<AuthService>(AuthService);
+  });
+
+  it('should register user', async () => {
+    // Test implementation
+  });
+});
+```
+
+### Integration Tests
+
+**Single example:** `server/test/app.e2e-spec.ts`
+
+**Scope:**
+- Tests full HTTP request/response cycle
+- Uses real app instance
+- Uses Test.createTestingModule() to create app
+
+**Pattern:**
+```typescript
+return request(app.getHttpServer())
+  .post('/auth/login')
+  .send({ identifier: 'user', password: 'pass' })
+  .expect(200)
+  .expect((res) => {
+    expect(res.body.token).toBeDefined();
+  });
+```
+
+**Would need:** Database test fixtures, cleanup between tests
+
+### E2E Tests
+
+**Config:** `server/test/jest-e2e.json`
+
+**Difference from Integration:**
+- Run against deployed/separate server
+- Test user workflows end-to-end
+- Full database setup/teardown
+
+**Currently:** Not implemented beyond placeholder
+
+## Common Patterns
+
+### Async Testing
+
+**Server (Jest):**
+```typescript
+it('should load data', async () => {
+  const result = await service.loadData();
+  expect(result).toBeDefined();
+});
+```
+
+- async/await preferred
+- Supertest chainable: `request().post().send().expect()`
+
+**Client (not yet implemented):**
+Would use:
+```typescript
+const { result } = await renderHook(() => useCharacterSocket());
+await waitFor(() => expect(result.current.socket).toBeDefined());
+```
+
+### Error Testing
+
+**Not yet implemented, but pattern would be:**
+
+**Server:**
+```typescript
+it('should throw NotFoundException', async () => {
+  await expect(service.getCharacter('invalid-id'))
+    .rejects
+    .toThrow(NotFoundException);
+});
+```
+
+**Actual exception handling verified through:**
+- Controllers catch exceptions
+- Guards handle auth failures
+- Integration tests verify HTTP status codes
+
+## Critical Test Gaps
+
+**High Priority (Authentication):**
+- AuthService.register() - conflicts, hashing, JWT generation
+- AuthService.login() - invalid credentials, token generation
+- JWT guard - token validation, public routes
+- File: `server/src/modules/auth/auth.service.ts` (lines 20-104)
+
+**High Priority (Character Management):**
+- CharactersService access control (checkCampaignAccess, checkCharacterAccess)
+- HP updates and state sync via WebSocket
+- Condition application (dying, wounded, doomed mechanics)
+- Item management (equip, invest, notes)
+- File: `server/src/modules/characters/characters.service.ts`
+
+**High Priority (Real-time Sync):**
+- CharactersGateway connection authentication
+- WebSocket message broadcasting
+- Concurrent client updates
+- File: `server/src/modules/characters/characters.gateway.ts`
+
+**Medium Priority (Client UI):**
+- HpControl component (damage, heal, direct modes)
+- AddConditionModal (search, filtering, validation)
+- Character import from Pathbuilder JSON
+- File: `client/src/features/characters/components/`
+
+**Medium Priority (Validation):**
+- DTO validation (CreateCharacterDto, LoginDto)
+- Prisma query results
+- File: `server/src/modules/*/dto/`
+
+## Recommendations for Implementation
+
+**Phase 1 (Auth):**
+1. Write AuthService unit tests with mocked Prisma
+2. Write JwtAuthGuard tests
+3. Write integration tests for login/register endpoints
+
+**Phase 2 (Character CRUD):**
+1. Test CharactersService access control
+2. Test HP update logic
+3. Test condition application
+
+**Phase 3 (WebSocket):**
+1. Mock socket.io for gateway tests
+2. Test connection/disconnect
+3. Test broadcast patterns
+
+**Phase 4 (Client):**
+1. Setup vitest
+2. Test HpControl component
+3. Test modal components
+4. Test Zustand store
+
+---
+
+*Testing analysis: 2026-04-27*