Part 2: Unit Testing with TypeScript

Introduction

Unit testing is the foundation of a solid test suite. In my TypeScript microservices, unit tests make up 70% of my test coverage and catch most bugs before they reach integration testing. They run in seconds, giving instant feedback during development.

This part covers practical unit testing techniques I use daily in production microservices—no theoretical examples, just real patterns that work.

What Makes a Good Unit Test?

A unit test should be:

1. Fast - Milliseconds, not seconds

2. Isolated - No external dependencies

3. Repeatable - Same result every time

4. Self-validating - Clear pass/fail

5. Timely - Written with (or before) production code

Example: Order Calculation Service

// src/services/order-calculator.ts
export interface OrderItem {
  productId: string;
  price: number;
  quantity: number;
}

export interface TaxRate {
  state: string;
  rate: number;
}

export class OrderCalculator {
  calculateSubtotal(items: OrderItem[]): number {
    return items.reduce((sum, item) => {
      return sum + (item.price * item.quantity);
    }, 0);
  }

  calculateTax(subtotal: number, taxRate: TaxRate): number {
    return subtotal * taxRate.rate;
  }

  calculateTotal(items: OrderItem[], taxRate: TaxRate): number {
    const subtotal = this.calculateSubtotal(items);
    const tax = this.calculateTax(subtotal, taxRate);
    return subtotal + tax;
  }

  applyDiscount(total: number, discountPercent: number): number {
    if (discountPercent < 0 || discountPercent > 100) {
      throw new Error('Discount must be between 0 and 100');
    }
    return total * (1 - discountPercent / 100);
  }
}

Comprehensive Unit Tests:

// src/services/__tests__/order-calculator.test.ts
import { OrderCalculator, OrderItem, TaxRate } from '../order-calculator';

describe('OrderCalculator', () => {
  let calculator: OrderCalculator;

  beforeEach(() => {
    calculator = new OrderCalculator();
  });

  describe('calculateSubtotal', () => {
    it('should calculate subtotal for single item', () => {
      const items: OrderItem[] = [
        { productId: '1', price: 10.00, quantity: 2 }
      ];

      const result = calculator.calculateSubtotal(items);

      expect(result).toBe(20.00);
    });

    it('should calculate subtotal for multiple items', () => {
      const items: OrderItem[] = [
        { productId: '1', price: 10.00, quantity: 2 },
        { productId: '2', price: 15.50, quantity: 3 },
        { productId: '3', price: 5.25, quantity: 1 }
      ];

      const result = calculator.calculateSubtotal(items);

      expect(result).toBe(71.75); // (10*2) + (15.50*3) + (5.25*1)
    });

    it('should return 0 for empty items array', () => {
      const result = calculator.calculateSubtotal([]);
      expect(result).toBe(0);
    });

    it('should handle decimal prices correctly', () => {
      const items: OrderItem[] = [
        { productId: '1', price: 9.99, quantity: 3 }
      ];

      const result = calculator.calculateSubtotal(items);

      expect(result).toBeCloseTo(29.97, 2);
    });
  });

  describe('calculateTax', () => {
    it('should calculate tax for California rate', () => {
      const taxRate: TaxRate = { state: 'CA', rate: 0.0725 };
      const result = calculator.calculateTax(100, taxRate);

      expect(result).toBe(7.25);
    });

    it('should calculate tax for Texas rate', () => {
      const taxRate: TaxRate = { state: 'TX', rate: 0.0625 };
      const result = calculator.calculateTax(100, taxRate);

      expect(result).toBe(6.25);
    });

    it('should return 0 for zero tax rate', () => {
      const taxRate: TaxRate = { state: 'OR', rate: 0 };
      const result = calculator.calculateTax(100, taxRate);

      expect(result).toBe(0);
    });
  });

  describe('calculateTotal', () => {
    it('should calculate total with tax', () => {
      const items: OrderItem[] = [
        { productId: '1', price: 50.00, quantity: 2 }
      ];
      const taxRate: TaxRate = { state: 'CA', rate: 0.10 };

      const result = calculator.calculateTotal(items, taxRate);

      expect(result).toBe(110.00); // (50*2) + (100*0.10)
    });
  });

  describe('applyDiscount', () => {
    it('should apply 10% discount correctly', () => {
      const result = calculator.applyDiscount(100, 10);
      expect(result).toBe(90);
    });

    it('should apply 25% discount correctly', () => {
      const result = calculator.applyDiscount(100, 25);
      expect(result).toBe(75);
    });

    it('should handle 0% discount', () => {
      const result = calculator.applyDiscount(100, 0);
      expect(result).toBe(100);
    });

    it('should handle 100% discount', () => {
      const result = calculator.applyDiscount(100, 100);
      expect(result).toBe(0);
    });

    it('should throw error for negative discount', () => {
      expect(() => calculator.applyDiscount(100, -10)).toThrow(
        'Discount must be between 0 and 100'
      );
    });

    it('should throw error for discount over 100', () => {
      expect(() => calculator.applyDiscount(100, 150)).toThrow(
        'Discount must be between 0 and 100'
      );
    });
  });
});

Testing Async Code

Most real-world TypeScript code is asynchronous. Here's how I test it effectively.

Example: User Service with Database

// src/services/user-service.ts
import { v4 as uuidv4 } from 'uuid';

export interface User {
  id: string;
  email: string;
  name: string;
  createdAt: Date;
}

export interface CreateUserDto {
  email: string;
  name: string;
}

export interface IUserRepository {
  save(user: User): Promise<void>;
  findByEmail(email: string): Promise<User | null>;
  findById(id: string): Promise<User | null>;
}

export class UserService {
  constructor(private readonly userRepository: IUserRepository) {}

  async createUser(dto: CreateUserDto): Promise<User> {
    // Validate email
    if (!this.isValidEmail(dto.email)) {
      throw new Error('Invalid email format');
    }

    // Check if user already exists
    const existing = await this.userRepository.findByEmail(dto.email);
    if (existing) {
      throw new Error('User with this email already exists');
    }

    // Create user
    const user: User = {
      id: uuidv4(),
      email: dto.email,
      name: dto.name,
      createdAt: new Date(),
    };

    await this.userRepository.save(user);
    return user;
  }

  async getUserById(id: string): Promise<User> {
    const user = await this.userRepository.findById(id);
    if (!user) {
      throw new Error(`User not found: ${id}`);
    }
    return user;
  }

  private isValidEmail(email: string): boolean {
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return emailRegex.test(email);
  }
}

Unit Tests with Mocks:

// src/services/__tests__/user-service.test.ts
import { UserService, IUserRepository, User } from '../user-service';

describe('UserService', () => {
  let userService: UserService;
  let mockRepository: jest.Mocked<IUserRepository>;

  beforeEach(() => {
    // Create mock repository
    mockRepository = {
      save: jest.fn(),
      findByEmail: jest.fn(),
      findById: jest.fn(),
    };

    userService = new UserService(mockRepository);
  });

  describe('createUser', () => {
    it('should create user with valid data', async () => {
      mockRepository.findByEmail.mockResolvedValue(null);
      mockRepository.save.mockResolvedValue();

      const dto = {
        email: '[email protected]',
        name: 'Test User',
      };

      const user = await userService.createUser(dto);

      expect(user.id).toBeDefined();
      expect(user.email).toBe(dto.email);
      expect(user.name).toBe(dto.name);
      expect(user.createdAt).toBeInstanceOf(Date);
      expect(mockRepository.save).toHaveBeenCalledWith(user);
    });

    it('should check if user exists before creating', async () => {
      mockRepository.findByEmail.mockResolvedValue(null);

      const dto = {
        email: '[email protected]',
        name: 'Test User',
      };

      await userService.createUser(dto);

      expect(mockRepository.findByEmail).toHaveBeenCalledWith(dto.email);
    });

    it('should throw error if user already exists', async () => {
      const existingUser: User = {
        id: '123',
        email: '[email protected]',
        name: 'Existing User',
        createdAt: new Date(),
      };

      mockRepository.findByEmail.mockResolvedValue(existingUser);

      const dto = {
        email: '[email protected]',
        name: 'Test User',
      };

      await expect(userService.createUser(dto)).rejects.toThrow(
        'User with this email already exists'
      );
      expect(mockRepository.save).not.toHaveBeenCalled();
    });

    it('should throw error for invalid email', async () => {
      const dto = {
        email: 'invalid-email',
        name: 'Test User',
      };

      await expect(userService.createUser(dto)).rejects.toThrow(
        'Invalid email format'
      );
      expect(mockRepository.findByEmail).not.toHaveBeenCalled();
    });
  });

  describe('getUserById', () => {
    it('should return user when found', async () => {
      const user: User = {
        id: '123',
        email: '[email protected]',
        name: 'Test User',
        createdAt: new Date(),
      };

      mockRepository.findById.mockResolvedValue(user);

      const result = await userService.getUserById('123');

      expect(result).toEqual(user);
      expect(mockRepository.findById).toHaveBeenCalledWith('123');
    });

    it('should throw error when user not found', async () => {
      mockRepository.findById.mockResolvedValue(null);

      await expect(userService.getUserById('999')).rejects.toThrow(
        'User not found: 999'
      );
    });
  });
});

Mocking and Stubbing

When to Mock

I mock:

• External services (APIs, databases)

• Time-dependent functions

• Random number generators

• File system operations

• Network calls

Example: Testing Time-Dependent Code

// src/services/subscription-service.ts
export interface Subscription {
  id: string;
  userId: string;
  startDate: Date;
  endDate: Date;
}

export class SubscriptionService {
  isActive(subscription: Subscription): boolean {
    const now = new Date();
    return now >= subscription.startDate && now <= subscription.endDate;
  }

  daysRemaining(subscription: Subscription): number {
    const now = new Date();
    if (now > subscription.endDate) {
      return 0;
    }
    const diff = subscription.endDate.getTime() - now.getTime();
    return Math.ceil(diff / (1000 * 60 * 60 * 24));
  }
}

Testing with mocked dates:

// src/services/__tests__/subscription-service.test.ts
import { SubscriptionService, Subscription } from '../subscription-service';

describe('SubscriptionService', () => {
  let service: SubscriptionService;
  let mockDate: Date;

  beforeEach(() => {
    service = new SubscriptionService();
    
    // Mock current date to 2024-06-15
    mockDate = new Date('2024-06-15T12:00:00Z');
    jest.useFakeTimers();
    jest.setSystemTime(mockDate);
  });

  afterEach(() => {
    jest.useRealTimers();
  });

  describe('isActive', () => {
    it('should return true for active subscription', () => {
      const subscription: Subscription = {
        id: '1',
        userId: 'user1',
        startDate: new Date('2024-06-01T00:00:00Z'),
        endDate: new Date('2024-06-30T23:59:59Z'),
      };

      expect(service.isActive(subscription)).toBe(true);
    });

    it('should return false for expired subscription', () => {
      const subscription: Subscription = {
        id: '1',
        userId: 'user1',
        startDate: new Date('2024-05-01T00:00:00Z'),
        endDate: new Date('2024-05-31T23:59:59Z'),
      };

      expect(service.isActive(subscription)).toBe(false);
    });

    it('should return false for future subscription', () => {
      const subscription: Subscription = {
        id: '1',
        userId: 'user1',
        startDate: new Date('2024-07-01T00:00:00Z'),
        endDate: new Date('2024-07-31T23:59:59Z'),
      };

      expect(service.isActive(subscription)).toBe(false);
    });
  });

  describe('daysRemaining', () => {
    it('should calculate days remaining correctly', () => {
      const subscription: Subscription = {
        id: '1',
        userId: 'user1',
        startDate: new Date('2024-06-01T00:00:00Z'),
        endDate: new Date('2024-06-20T23:59:59Z'),
      };

      // Current mock date: 2024-06-15, end date: 2024-06-20
      expect(service.daysRemaining(subscription)).toBe(6);
    });

    it('should return 0 for expired subscription', () => {
      const subscription: Subscription = {
        id: '1',
        userId: 'user1',
        startDate: new Date('2024-05-01T00:00:00Z'),
        endDate: new Date('2024-05-31T23:59:59Z'),
      };

      expect(service.daysRemaining(subscription)).toBe(0);
    });
  });
});

Testing Error Handling

Proper error handling is critical in production systems. I always test error paths.

Example: Payment Service

// src/services/payment-service.ts
export interface PaymentProvider {
  charge(amount: number, token: string): Promise<{ success: boolean; transactionId?: string; error?: string }>;
}

export class PaymentService {
  constructor(private readonly provider: PaymentProvider) {}

  async processPayment(amount: number, token: string): Promise<string> {
    if (amount <= 0) {
      throw new Error('Amount must be greater than 0');
    }

    if (!token) {
      throw new Error('Payment token is required');
    }

    try {
      const result = await this.provider.charge(amount, token);
      
      if (!result.success) {
        throw new Error(`Payment failed: ${result.error}`);
      }

      if (!result.transactionId) {
        throw new Error('Transaction ID not received');
      }

      return result.transactionId;
    } catch (error) {
      if (error instanceof Error) {
        throw new Error(`Payment processing error: ${error.message}`);
      }
      throw new Error('Unknown payment error');
    }
  }
}

Error handling tests:

// src/services/__tests__/payment-service.test.ts
import { PaymentService, PaymentProvider } from '../payment-service';

describe('PaymentService', () => {
  let service: PaymentService;
  let mockProvider: jest.Mocked<PaymentProvider>;

  beforeEach(() => {
    mockProvider = {
      charge: jest.fn(),
    };
    service = new PaymentService(mockProvider);
  });

  describe('processPayment', () => {
    it('should process payment successfully', async () => {
      mockProvider.charge.mockResolvedValue({
        success: true,
        transactionId: 'txn_123',
      });

      const result = await service.processPayment(100, 'tok_123');

      expect(result).toBe('txn_123');
      expect(mockProvider.charge).toHaveBeenCalledWith(100, 'tok_123');
    });

    it('should throw error for zero amount', async () => {
      await expect(service.processPayment(0, 'tok_123')).rejects.toThrow(
        'Amount must be greater than 0'
      );
      expect(mockProvider.charge).not.toHaveBeenCalled();
    });

    it('should throw error for negative amount', async () => {
      await expect(service.processPayment(-50, 'tok_123')).rejects.toThrow(
        'Amount must be greater than 0'
      );
    });

    it('should throw error for missing token', async () => {
      await expect(service.processPayment(100, '')).rejects.toThrow(
        'Payment token is required'
      );
    });

    it('should throw error when provider charge fails', async () => {
      mockProvider.charge.mockResolvedValue({
        success: false,
        error: 'Insufficient funds',
      });

      await expect(service.processPayment(100, 'tok_123')).rejects.toThrow(
        'Payment processing error: Payment failed: Insufficient funds'
      );
    });

    it('should throw error when transaction ID not received', async () => {
      mockProvider.charge.mockResolvedValue({
        success: true,
      });

      await expect(service.processPayment(100, 'tok_123')).rejects.toThrow(
        'Payment processing error: Transaction ID not received'
      );
    });

    it('should handle provider exceptions', async () => {
      mockProvider.charge.mockRejectedValue(new Error('Network timeout'));

      await expect(service.processPayment(100, 'tok_123')).rejects.toThrow(
        'Payment processing error: Network timeout'
      );
    });
  });
});

Parameterized Tests

When testing multiple similar scenarios, use parameterized tests to reduce duplication.

// src/utils/validators.ts
export class Validators {
  static isValidPassword(password: string): boolean {
    return password.length >= 8 &&
           /[A-Z]/.test(password) &&
           /[a-z]/.test(password) &&
           /[0-9]/.test(password);
  }
}

Parameterized tests:

// src/utils/__tests__/validators.test.ts
import { Validators } from '../validators';

describe('Validators', () => {
  describe('isValidPassword', () => {
    // Test valid passwords
    it.each([
      ['ValidPass1', true],
      ['MySecureP@ss123', true],
      ['Abcd1234', true],
    ])('should return %s for password "%s"', (password, expected) => {
      expect(Validators.isValidPassword(password)).toBe(expected);
    });

    // Test invalid passwords
    it.each([
      ['short', 'too short'],
      ['nouppercase1', 'no uppercase'],
      ['NOLOWERCASE1', 'no lowercase'],
      ['NoNumbers', 'no numbers'],
      ['', 'empty string'],
    ])('should return false for %s: "%s"', (password, _reason) => {
      expect(Validators.isValidPassword(password)).toBe(false);
    });
  });
});

Test Helpers and Factories

For complex objects, use factory functions to create test data.

// src/test-helpers/factories.ts
import { User, Order, OrderItem } from '../types';

export class TestFactories {
  static createUser(overrides: Partial<User> = {}): User {
    return {
      id: 'user-123',
      email: '[email protected]',
      name: 'Test User',
      createdAt: new Date('2024-01-01'),
      ...overrides,
    };
  }

  static createOrder(overrides: Partial<Order> = {}): Order {
    return {
      id: 'order-123',
      userId: 'user-123',
      items: [],
      subtotal: 0,
      tax: 0,
      total: 0,
      status: 'pending',
      createdAt: new Date('2024-01-01'),
      ...overrides,
    };
  }

  static createOrderItem(overrides: Partial<OrderItem> = {}): OrderItem {
    return {
      productId: 'prod-123',
      name: 'Test Product',
      price: 10.00,
      quantity: 1,
      ...overrides,
    };
  }
}

Using factories in tests:

// src/services/__tests__/order-service.test.ts
import { TestFactories } from '../../test-helpers/factories';

describe('OrderService', () => {
  it('should calculate order total correctly', () => {
    const order = TestFactories.createOrder({
      items: [
        TestFactories.createOrderItem({ price: 10.00, quantity: 2 }),
        TestFactories.createOrderItem({ price: 15.00, quantity: 1 }),
      ],
    });

    const total = orderService.calculateTotal(order);
    expect(total).toBe(35.00);
  });
});

Test-Driven Development (TDD)

TDD means writing tests before implementation. In my experience, TDD works best for:

• Business logic with clear requirements

• Utility functions with defined inputs/outputs

• Bug fixes (write failing test, then fix)

TDD Example: Email Validator

Step 1: Write failing test

// src/utils/__tests__/email-validator.test.ts
import { EmailValidator } from '../email-validator';

describe('EmailValidator', () => {
  it('should validate correct email', () => {
    expect(EmailValidator.isValid('[email protected]')).toBe(true);
  });

  it('should reject email without @', () => {
    expect(EmailValidator.isValid('testexample.com')).toBe(false);
  });

  it('should reject email without domain', () => {
    expect(EmailValidator.isValid('test@')).toBe(false);
  });
});

Step 2: Run tests (they fail)

npm test
# FAIL - EmailValidator not found

Step 3: Implement minimum code

// src/utils/email-validator.ts
export class EmailValidator {
  static isValid(email: string): boolean {
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return emailRegex.test(email);
  }
}

Step 4: Tests pass

npm test
# PASS - All tests pass

Step 5: Refactor if needed

Best Practices from Production

1. Keep Tests Fast

// Bad: Slow test due to actual delays
it('should timeout after 5 seconds', async () => {
  await new Promise(resolve => setTimeout(resolve, 5000));
  // test logic
});

// Good: Use fake timers
it('should timeout after 5 seconds', () => {
  jest.useFakeTimers();
  
  const callback = jest.fn();
  setTimeout(callback, 5000);
  
  jest.advanceTimersByTime(5000);
  expect(callback).toHaveBeenCalled();
  
  jest.useRealTimers();
});

2. Test Edge Cases

Always test:

• Empty inputs

• Null/undefined

• Boundary values

• Maximum/minimum values

• Special characters

3. Use Descriptive Assertions

// Bad
expect(result).toBe(true);

// Good
expect(result).toBe(true); // User should be authenticated
// or
expect(user.isAuthenticated).toBe(true);

4. Don't Test Third-Party Code

// Don't test that bcrypt works
it('should hash password', async () => {
  const hash = await bcrypt.hash('password', 10);
  expect(hash).toBeDefined();
});

// Test YOUR code that uses bcrypt
it('should hash password using service', async () => {
  const hasher = new PasswordHasher();
  const hash = await hasher.hash('MyPassword123');
  
  expect(hash).toBeDefined();
  expect(await hasher.compare('MyPassword123', hash)).toBe(true);
});

Common Pitfalls

1. Over-Mocking

// Bad: Mocking everything defeats the purpose
const mockAdd = jest.fn((a, b) => a + b);
const mockMultiply = jest.fn((a, b) => a * b);

// Good: Only mock external dependencies
const mockDatabase = {
  save: jest.fn(),
  find: jest.fn(),
};

2. Brittle Tests

// Bad: Test breaks when implementation changes
expect(userService.createUser).toHaveBeenCalledTimes(1);

// Good: Test behavior, not implementation
const user = await userService.createUser({ email: '[email protected]' });
expect(user.email).toBe('[email protected]');

Key Takeaways

1. Unit tests are fast and isolated - No external dependencies

2. Mock external services - Database, APIs, file system

3. Test error cases - Not just happy paths

4. Use AAA pattern - Arrange, Act, Assert

5. Leverage factories - Create test data easily

6. Test time-dependent code - Use fake timers

7. TDD when it makes sense - Especially for business logic

8. Keep tests maintainable - They're code too

What's Next?

In Part 3: Integration Testing, we'll cover:

• Testing with real databases

• API integration tests

• Testing message queues

• Container-based testing

• Integration test patterns

---

This article is part of the Software Testing 101 series.