07 - Testing e Qualità del Codice con Claude

Testing e qualità del Codice con Claude Code

I test sono il fondamento di un progetto manutenibile. Non sono solo una rete di sicurezza contro i bug, ma anche documentazione eseguibile che descrive come il codice dovrebbe comportarsi. Claude Code può accelerare drasticamente la scrittura di test, dal TDD al refactoring guidato, dal debugging assistito alla copertura dei casi edge.

In questo articolo esploreremo come sfruttare Claude Code per ogni livello della piramide dei test, con prompt specifici, esempi pratici e best practices per ottenere test robusti e manutenibili.

La Piramide dei Test

La piramide dei test definisce la strategia ottimale per bilanciare velocità, copertura e manutenibilità. Claude Code può aiutarti a tutti i livelli.

                    /\
                   /  \
                  / E2E\           Pochi (5-10%)
                 /------\            Lenti, costosi, fragili
                /        \           Testano flussi utente completi
               /Integration\      Moderati (15-25%)
              /--------------\      Velocita media
             /                \     Testano interazioni tra componenti
            /   Unit Tests     \  Molti (70-80%)
           /--------------------\   Veloci, isolati, stabili
          /                      \  Testano singole unita
         /________________________\

Strategia di Test con Claude Code

Claude Code eccelle nel generare test completi partendo dal codice esistente. Ecco la strategia ottimale:

Generazione Unit Test

Gli unit test verificano singole funzioni o classi in isolamento completo. Sono veloci, affidabili e forniscono feedback immediato durante lo sviluppo.

Prompt per Generare Unit Test

Generate comprehensive unit tests for this service:

```typescript
[PASTE SERVICE CODE HERE]
```

TESTING REQUIREMENTS:
- Framework: Jest with TypeScript
- Coverage target: >90% for this critical service
- Mock ALL external dependencies (repositories, external services)

TEST CATEGORIES TO COVER:
1. Happy Path: Normal successful operations
2. Validation: Invalid inputs, edge cases
3. Error Handling: Expected errors are thrown correctly
4. Edge Cases: Empty arrays, null values, boundary conditions
5. State Changes: Verify side effects (calls to dependencies)

OUTPUT FORMAT:
- Complete test file with all imports
- Use describe/it blocks with clear descriptions
- Include beforeEach for setup
- Group tests by method
- Use AAA pattern (Arrange, Act, Assert)
- Add comments explaining non-obvious test cases

NAMING CONVENTION:
- Describe: "ServiceName"
- Nested describe: "methodName"
- It: "should [expected behavior] when [condition]"

Esempio Completo: UserService Unit Tests

import {{ '{' }} UserService {{ '}' }} from './user.service';
import {{ '{' }} UserRepository {{ '}' }} from './user.repository';
import {{ '{' }} EmailService {{ '}' }} from '@shared/services/email.service';
import {{ '{' }} ValidationError, NotFoundError, ConflictError {{ '}' }} from '@shared/errors';
import {{ '{' }} createUserFixture, validUserDto {{ '}' }} from './fixtures/user.fixtures';

describe('UserService', () => {{ '{' }}
  let service: UserService;
  let mockUserRepository: jest.Mocked<UserRepository>;
  let mockEmailService: jest.Mocked<EmailService>;

  beforeEach(() => {{ '{' }}
    // Create fresh mocks for each test
    mockUserRepository = {{ '{' }}
      findById: jest.fn(),
      findByEmail: jest.fn(),
      create: jest.fn(),
      update: jest.fn(),
      softDelete: jest.fn(),
      findAll: jest.fn(),
    {{ '}' }} as any;

    mockEmailService = {{ '{' }}
      sendWelcomeEmail: jest.fn(),
      sendPasswordResetEmail: jest.fn(),
    {{ '}' }} as any;

    service = new UserService(mockUserRepository, mockEmailService);
  {{ '}' }});

  afterEach(() => {{ '{' }}
    jest.clearAllMocks();
  {{ '}' }});

  // ================================================
  // CREATE USER
  // ================================================
  describe('createUser', () => {{ '{' }}
    describe('happy path', () => {{ '{' }}
      it('should create user and send welcome email when valid data provided', async () => {{ '{' }}
        // Arrange
        const dto = validUserDto;
        const expectedUser = createUserFixture({{ '{' }} id: 'user-123', ...dto {{ '}' }});
        mockUserRepository.findByEmail.mockResolvedValue(null);
        mockUserRepository.create.mockResolvedValue(expectedUser);
        mockEmailService.sendWelcomeEmail.mockResolvedValue(undefined);

        // Act
        const result = await service.createUser(dto);

        // Assert
        expect(result.id).toBe('user-123');
        expect(result.email).toBe(dto.email);
        expect(mockUserRepository.create).toHaveBeenCalledWith(
          expect.objectContaining({{ '{' }}
            name: dto.name,
            email: dto.email,
          {{ '}' }})
        );
        expect(mockEmailService.sendWelcomeEmail).toHaveBeenCalledWith(
          expectedUser.email,
          expectedUser.name
        );
      {{ '}' }});
    {{ '}' }});

    describe('validation errors', () => {{ '{' }}
      it('should throw ConflictError when email already exists', async () => {{ '{' }}
        // Arrange
        const existingUser = createUserFixture({{ '{' }} email: 'exists@test.com' {{ '}' }});
        mockUserRepository.findByEmail.mockResolvedValue(existingUser);

        // Act & Assert
        await expect(
          service.createUser({{ '{' }} ...validUserDto, email: 'exists@test.com' {{ '}' }})
        ).rejects.toThrow(ConflictError);

        expect(mockUserRepository.create).not.toHaveBeenCalled();
        expect(mockEmailService.sendWelcomeEmail).not.toHaveBeenCalled();
      {{ '}' }});

      it('should throw ValidationError when password is too weak', async () => {{ '{' }}
        // Arrange
        mockUserRepository.findByEmail.mockResolvedValue(null);

        // Act & Assert
        await expect(
          service.createUser({{ '{' }} ...validUserDto, password: '123' {{ '}' }})
        ).rejects.toThrow(ValidationError);
      {{ '}' }});
    {{ '}' }});

    describe('edge cases', () => {{ '{' }}
      it('should trim whitespace from email', async () => {{ '{' }}
        // Arrange
        mockUserRepository.findByEmail.mockResolvedValue(null);
        mockUserRepository.create.mockResolvedValue(createUserFixture());

        // Act
        await service.createUser({{ '{' }}
          ...validUserDto,
          email: '  user@test.com  '
        {{ '}' }});

        // Assert
        expect(mockUserRepository.findByEmail).toHaveBeenCalledWith('user@test.com');
      {{ '}' }});

      it('should normalize email to lowercase', async () => {{ '{' }}
        // Arrange
        mockUserRepository.findByEmail.mockResolvedValue(null);
        mockUserRepository.create.mockResolvedValue(createUserFixture());

        // Act
        await service.createUser({{ '{' }}
          ...validUserDto,
          email: 'User@TEST.com'
        {{ '}' }});

        // Assert
        expect(mockUserRepository.findByEmail).toHaveBeenCalledWith('user@test.com');
      {{ '}' }});
    {{ '}' }});
  {{ '}' }});

  // ================================================
  // GET USER BY ID
  // ================================================
  describe('getUserById', () => {{ '{' }}
    it('should return user when found', async () => {{ '{' }}
      // Arrange
      const user = createUserFixture({{ '{' }} id: 'user-123' {{ '}' }});
      mockUserRepository.findById.mockResolvedValue(user);

      // Act
      const result = await service.getUserById('user-123');

      // Assert
      expect(result).toEqual(user);
      expect(mockUserRepository.findById).toHaveBeenCalledWith('user-123');
    {{ '}' }});

    it('should throw NotFoundError when user does not exist', async () => {{ '{' }}
      // Arrange
      mockUserRepository.findById.mockResolvedValue(null);

      // Act & Assert
      await expect(service.getUserById('non-existent'))
        .rejects.toThrow(NotFoundError);
    {{ '}' }});

    it('should throw ValidationError when id is empty', async () => {{ '{' }}
      await expect(service.getUserById('')).rejects.toThrow(ValidationError);
    {{ '}' }});
  {{ '}' }});
{{ '}' }});

Test di Integrazione

Gli integration test verificano che i componenti funzionino correttamente insieme. Testano l'API completa, incluso routing, middleware, validazione e accesso al database.

Prompt per Integration Tests

Generate integration tests for this API:

ENDPOINTS:
- POST   /api/users      - Create user (requires auth)
- GET    /api/users/:id  - Get user by ID
- PATCH  /api/users/:id  - Update user (owner only)
- DELETE /api/users/:id  - Soft delete (admin only)

TESTING REQUIREMENTS:
- Framework: Jest + Supertest
- Database: Test PostgreSQL (use transactions, rollback after each test)
- Auth: JWT tokens (mock or real test tokens)

TEST SCENARIOS FOR EACH ENDPOINT:
1. Success case with valid request
2. Validation errors (400) - invalid body, missing fields
3. Authentication errors (401) - missing/invalid token
4. Authorization errors (403) - wrong role/permissions
5. Not found errors (404) - resource doesn't exist
6. Conflict errors (409) - duplicate resources

SETUP/TEARDOWN:
- beforeAll: Create test database, run migrations
- beforeEach: Start transaction
- afterEach: Rollback transaction
- afterAll: Close database connection

Include helper functions for:
- Creating authenticated requests
- Generating test users
- Cleaning up test data

Esempio Integration Test

import request from 'supertest';
import {{ '{' }} app {{ '}' }} from '../app';
import {{ '{' }} db {{ '}' }} from '../database';
import {{ '{' }} createTestUser, getAuthToken, cleanupTestData {{ '}' }} from './helpers';
import {{ '{' }} UserRole {{ '}' }} from '@shared/types';

describe('Users API Integration Tests', () => {{ '{' }}
  let adminToken: string;
  let userToken: string;
  let testUserId: string;

  beforeAll(async () => {{ '{' }}
    await db.connect();
    await db.migrate();

    // Create test users and get tokens
    const admin = await createTestUser({{ '{' }} role: UserRole.ADMIN {{ '}' }});
    const user = await createTestUser({{ '{' }} role: UserRole.USER {{ '}' }});

    adminToken = await getAuthToken(admin);
    userToken = await getAuthToken(user);
    testUserId = user.id;
  {{ '}' }});

  afterAll(async () => {{ '{' }}
    await cleanupTestData();
    await db.disconnect();
  {{ '}' }});

  // ================================================
  // POST /api/users - Create User
  // ================================================
  describe('POST /api/users', () => {{ '{' }}
    const validPayload = {{ '{' }}
      name: 'Integration Test User',
      email: 'integration@test.com',
      password: 'SecurePass123!',
    {{ '}' }};

    describe('success cases', () => {{ '{' }}
      it('should create user with valid data (201)', async () => {{ '{' }}
        const response = await request(app)
          .post('/api/users')
          .set('Authorization', `Bearer ${{ '{' }}adminToken{{ '}' }}`)
          .send({{ '{' }} ...validPayload, email: `unique-${{ '{' }}Date.now(){{ '}' }}@test.com` {{ '}' }});

        expect(response.status).toBe(201);
        expect(response.body.data).toMatchObject({{ '{' }}
          name: validPayload.name,
          email: expect.stringContaining('@test.com'),
        {{ '}' }});
        expect(response.body.data.password).toBeUndefined();
        expect(response.body.data.id).toBeDefined();
      {{ '}' }});
    {{ '}' }});

    describe('validation errors (400)', () => {{ '{' }}
      it('should return 400 when email is invalid', async () => {{ '{' }}
        const response = await request(app)
          .post('/api/users')
          .set('Authorization', `Bearer ${{ '{' }}adminToken{{ '}' }}`)
          .send({{ '{' }} ...validPayload, email: 'not-an-email' {{ '}' }});

        expect(response.status).toBe(400);
        expect(response.body.error.code).toBe('VALIDATION_ERROR');
      {{ '}' }});
    {{ '}' }});

    describe('authentication errors (401)', () => {{ '{' }}
      it('should return 401 without auth token', async () => {{ '{' }}
        const response = await request(app)
          .post('/api/users')
          .send(validPayload);

        expect(response.status).toBe(401);
        expect(response.body.error.code).toBe('UNAUTHORIZED');
      {{ '}' }});
    {{ '}' }});

    describe('authorization errors (403)', () => {{ '{' }}
      it('should return 403 when non-admin tries to create user', async () => {{ '{' }}
        const response = await request(app)
          .post('/api/users')
          .set('Authorization', `Bearer ${{ '{' }}userToken{{ '}' }}`)
          .send(validPayload);

        expect(response.status).toBe(403);
        expect(response.body.error.code).toBe('FORBIDDEN');
      {{ '}' }});
    {{ '}' }});
  {{ '}' }});

  // ================================================
  // DELETE /api/users/:id - Soft Delete (Admin Only)
  // ================================================
  describe('DELETE /api/users/:id', () => {{ '{' }}
    it('should soft delete user when admin (204)', async () => {{ '{' }}
      const userToDelete = await createTestUser();

      const response = await request(app)
        .delete(`/api/users/${{ '{' }}userToDelete.id{{ '}' }}`)
        .set('Authorization', `Bearer ${{ '{' }}adminToken{{ '}' }}`);

      expect(response.status).toBe(204);

      // Verify user is soft deleted
      const getResponse = await request(app)
        .get(`/api/users/${{ '{' }}userToDelete.id{{ '}' }}`)
        .set('Authorization', `Bearer ${{ '{' }}adminToken{{ '}' }}`);

      expect(getResponse.status).toBe(404);
    {{ '}' }});

    it('should return 403 when non-admin tries to delete', async () => {{ '{' }}
      const response = await request(app)
        .delete(`/api/users/${{ '{' }}testUserId{{ '}' }}`)
        .set('Authorization', `Bearer ${{ '{' }}userToken{{ '}' }}`);

      expect(response.status).toBe(403);
    {{ '}' }});
  {{ '}' }});
{{ '}' }});

Refactor Guidato con Claude Code

Claude Code può suggerire refactoring mantenendo il comportamento. I test esistenti diventano la tua rete di sicurezza.

I want to refactor this code. I have tests that cover its behavior:

CURRENT CODE:
```typescript
[PASTE CODE]
```

EXISTING TESTS (passing):
```typescript
[PASTE TESTS]
```

REFACTORING GOALS:
1. Reduce cyclomatic complexity
2. Extract reusable functions
3. Improve naming

CONSTRAINTS:
- All existing tests MUST still pass
- Don't change public interface
- No new dependencies

Provide:
1. Refactored code
2. Explanation of each change
3. Any new tests needed for extracted functions

Debug Assistito con Claude Code

Claude Code è eccellente per analizzare errori e trovare la causa root.

This test is failing and I can't figure out why:

TEST:
```typescript
it('should apply discount to order total', async () => {{ '{' }}
  const order = await orderService.createOrder({{ '{' }}
    items: [{{ '{' }} productId: 'prod-1', quantity: 2 {{ '}' }}],
    couponCode: 'SAVE10',
  {{ '}' }});

  expect(order.total).toBe(90); // Expected $90 after 10% discount
  expect(order.discount).toBe(10);
{{ '}' }});
```

ERROR:
```
Expected: 90
Received: 100
```

IMPLEMENTATION:
```typescript
async createOrder(dto: CreateOrderDto): Promise<Order> {{ '{' }}
  const items = await this.getOrderItems(dto.items);
  const subtotal = items.reduce((sum, item) => sum + item.price * item.quantity, 0);

  let discount = 0;
  if (dto.couponCode) {{ '{' }}
    const coupon = await this.couponRepository.findByCode(dto.couponCode);
    if (coupon) {{ '{' }}
      discount = subtotal * (coupon.percentage / 100);
    {{ '}' }}
  {{ '}' }}

  return this.orderRepository.create({{ '{' }}
    items,
    subtotal,
    discount,
    total: subtotal - discount,
  {{ '}' }});
{{ '}' }}
```

Help me:
1. Identify why the test is failing
2. Determine if it's a test bug or implementation bug
3. Provide the fix

Code Review con Claude Code

Usa Claude Code per fare code review dei test stessi.

Review these tests for quality and completeness:

```typescript
[PASTE TESTS]
```

ANALYZE:
1. Test Coverage Gaps
   - Missing happy paths
   - Missing error scenarios
   - Missing edge cases

2. Test Quality Issues
   - Tests that test implementation vs behavior
   - Flaky test patterns
   - Poor isolation (shared state)
   - Missing assertions

3. Maintainability Issues
   - Unclear test names
   - Code duplication
   - Missing comments for complex scenarios

4. Best Practices Violations
   - Not using AAA pattern
   - Multiple assertions testing different things
   - Mocking too much or too little

For each issue provide:
- Location (line/describe block)
- Problem description
- Recommended fix with code example

Test Fixtures e Factories

Fixture ben strutturate rendono i test più leggibili e manutenibili.

// fixtures/user.fixtures.ts

import {{ '{' }} User, UserRole, UserStatus {{ '}' }} from '@/entities/user.entity';
import {{ '{' }} CreateUserDto {{ '}' }} from '@/dto/create-user.dto';

// ================================================
// BASE FIXTURES - Valid default values
// ================================================

export const validUserDto: CreateUserDto = {{ '{' }}
  name: 'Test User',
  email: 'test@example.com',
  password: 'SecurePassword123!',
{{ '}' }};

export const validUser: Partial<User> = {{ '{' }}
  id: 'user-123',
  name: 'Test User',
  email: 'test@example.com',
  role: UserRole.USER,
  status: UserStatus.ACTIVE,
  createdAt: new Date('2025-01-01'),
  updatedAt: new Date('2025-01-01'),
{{ '}' }};

// ================================================
// FACTORY FUNCTION - Create users with overrides
// ================================================

let userCounter = 0;

export function createUserFixture(overrides: Partial<User> = {{ '{' }}{{ '}' }}): User {{ '{' }}
  userCounter++;
  return {{ '{' }}
    id: `user-${{ '{' }}userCounter{{ '}' }}`,
    name: 'Test User',
    email: `test-${{ '{' }}userCounter{{ '}' }}@example.com`,
    password: '$2b$10$hashedpassword',
    role: UserRole.USER,
    status: UserStatus.ACTIVE,
    createdAt: new Date(),
    updatedAt: new Date(),
    deletedAt: null,
    ...overrides,
  {{ '}' }} as User;
{{ '}' }}

// ================================================
// INVALID FIXTURES - For testing validation
// ================================================

export const invalidUserDtos = {{ '{' }}
  missingName: {{ '{' }}
    email: 'test@example.com',
    password: 'SecurePassword123!',
  {{ '}' }},
  invalidEmail: {{ '{' }}
    name: 'Test User',
    email: 'not-an-email',
    password: 'SecurePassword123!',
  {{ '}' }},
  weakPassword: {{ '{' }}
    name: 'Test User',
    email: 'test@example.com',
    password: '123',
  {{ '}' }},
{{ '}' }};

// ================================================
// SCENARIO FIXTURES - Specific test scenarios
// ================================================

export const userScenarios = {{ '{' }}
  admin: () => createUserFixture({{ '{' }} role: UserRole.ADMIN {{ '}' }}),
  inactive: () => createUserFixture({{ '{' }} status: UserStatus.INACTIVE {{ '}' }}),
  deleted: () => createUserFixture({{ '{' }}
    status: UserStatus.DELETED,
    deletedAt: new Date(),
  {{ '}' }}),
{{ '}' }};

// ================================================
// HELPERS
// ================================================

export function resetUserFixtures(): void {{ '{' }}
  userCounter = 0;
{{ '}' }}

TDD Workflow con Claude Code

Il Test-Driven Development funziona ancora meglio con Claude Code. Scrivi prima il test, poi lascia che Claude suggerisca l'implementazione.

I'm following TDD. Here's my failing test:

```typescript
describe('calculateDiscount', () => {{ '{' }}
  it('should apply 10% discount for orders over $100', () => {{ '{' }}
    expect(calculateDiscount(150)).toBe(15);
  {{ '}' }});

  it('should apply 20% discount for orders over $500', () => {{ '{' }}
    expect(calculateDiscount(600)).toBe(120);
  {{ '}' }});

  it('should return 0 for orders under $100', () => {{ '{' }}
    expect(calculateDiscount(50)).toBe(0);
  {{ '}' }});
{{ '}' }});
```

1. Implement the MINIMUM code to make these tests pass
2. Don't add features not covered by tests
3. After implementation, suggest additional edge cases I should test

Test Coverage e Gap Analysis

Usa Claude Code per identificare codice non coperto e generare test mancanti.

My coverage report shows uncovered lines:

FILE: src/services/order.service.ts
UNCOVERED LINES: 45-52, 78-85, 120-135

Here's the code at those lines:

```typescript
// Lines 45-52
if (order.status === 'cancelled') {{ '{' }}
  throw new ValidationError('Cannot modify cancelled order');
{{ '}' }}

// Lines 78-85
if (items.some(item => item.quantity > item.stock)) {{ '{' }}
  const outOfStock = items.filter(i => i.quantity > i.stock);
  throw new ValidationError(`Insufficient stock for: ${{ '{' }}outOfStock.map(i => i.name).join(', '){{ '}' }}`);
{{ '}' }}

// Lines 120-135
if (coupon && coupon.expiresAt < new Date()) {{ '{' }}
  throw new ValidationError('Coupon has expired');
{{ '}' }}
if (coupon && coupon.usageCount >= coupon.maxUsage) {{ '{' }}
  throw new ValidationError('Coupon usage limit reached');
{{ '}' }}
```

Generate unit tests to cover these scenarios. Include:
1. Test for each branch
2. Boundary conditions
3. Descriptive test names

Testing Best Practices

Checklist qualità dei Test

Conclusione e Prossimi Passi

Il testing è dove Claude Code brilla davvero. Può generare test completi partendo dal codice esistente, suggerire edge cases che potresti non aver considerato, e aiutarti a mantenere alta la coverage senza sacrificare la velocità di sviluppo.

Ricorda: i test generati da Claude Code devono sempre essere verificati. L'AI può generare test che passano ma non testano realmente il comportamento importante, o che sono troppo legati all'implementazione invece che al comportamento.

Nel prossimo articolo vedremo come usare Claude Code per la documentazione professionale: README completi, API documentation con OpenAPI, Architecture Decision Records e JSDoc.