# 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*