Part 1: Introduction and Testing Fundamentals

Introduction

Testing isn't just about finding bugs—it's about building confidence that your code works as expected. In my years of building and maintaining TypeScript microservices, I've learned that solid testing practices are what separate hobby projects from production-ready systems.

This series covers practical software testing using TypeScript microservices as examples. These aren't theoretical scenarios—they're patterns I use daily in real production systems handling thousands of requests.

Why Testing Matters

Early in my career, I deployed a payment service without comprehensive tests. A simple edge case I missed caused payment failures for 2 hours during peak traffic. That incident taught me testing isn't optional—it's insurance against production disasters.

Real Impact of Testing

From my production experience:

• Faster development: Tests let me refactor confidently without breaking existing features

• Better code design: Writing testable code forces better architecture

• Documentation: Tests show how code should be used

• Regression prevention: Once fixed, bugs stay fixed

• Sleep better: Comprehensive tests mean fewer 3 AM pages

The Testing Pyramid

In my microservices architecture, I follow this distribution:

        /\
       /  \
      /E2E \          10% - End-to-End Tests
     /------\         
    /        \
   /Integration\      20% - Integration Tests
  /-------------\
 /               \
/   Unit Tests   \    70% - Unit Tests
------------------

Why This Ratio?

70% Unit Tests:

• Fast execution (milliseconds)

• Isolated from external dependencies

• Easy to debug when they fail

• Test business logic thoroughly

20% Integration Tests:

• Verify components work together

• Test database interactions

• Validate API contracts

• Moderate execution speed

10% E2E Tests:

• Test critical user journeys

• Validate entire system flow

• Slower but provide high confidence

• Focus on happy paths and critical scenarios

In my order processing microservice, this pyramid means:

• 1,200+ unit tests (run in 15 seconds)

• 300+ integration tests (run in 2 minutes)

• 50 E2E tests (run in 8 minutes)

Total test suite: under 10 minutes, giving fast feedback on every commit.

Types of Software Testing

1. Unit Testing

Testing individual functions or classes in isolation.

Example from my auth service:

// src/services/password-hasher.ts
import bcrypt from 'bcrypt';

export class PasswordHasher {
  private readonly saltRounds = 10;

  async hash(password: string): Promise<string> {
    if (!password || password.length < 8) {
      throw new Error('Password must be at least 8 characters');
    }
    return bcrypt.hash(password, this.saltRounds);
  }

  async compare(password: string, hash: string): Promise<boolean> {
    return bcrypt.compare(password, hash);
  }
}

Unit Test:

// src/services/__tests__/password-hasher.test.ts
import { PasswordHasher } from '../password-hasher';

describe('PasswordHasher', () => {
  let hasher: PasswordHasher;

  beforeEach(() => {
    hasher = new PasswordHasher();
  });

  describe('hash', () => {
    it('should hash valid password', async () => {
      const password = 'MySecureP@ss123';
      const hash = await hasher.hash(password);

      expect(hash).toBeDefined();
      expect(hash).not.toBe(password);
      expect(hash.length).toBeGreaterThan(password.length);
    });

    it('should throw error for short password', async () => {
      await expect(hasher.hash('short')).rejects.toThrow(
        'Password must be at least 8 characters'
      );
    });

    it('should throw error for empty password', async () => {
      await expect(hasher.hash('')).rejects.toThrow(
        'Password must be at least 8 characters'
      );
    });
  });

  describe('compare', () => {
    it('should return true for matching password', async () => {
      const password = 'MySecureP@ss123';
      const hash = await hasher.hash(password);

      const result = await hasher.compare(password, hash);
      expect(result).toBe(true);
    });

    it('should return false for non-matching password', async () => {
      const password = 'MySecureP@ss123';
      const hash = await hasher.hash(password);

      const result = await hasher.compare('WrongPassword', hash);
      expect(result).toBe(false);
    });
  });
});

2. Integration Testing

Testing how components interact with each other and external systems.

Example: Testing repository layer with real database.

// src/repositories/__tests__/user-repository.integration.test.ts
import { UserRepository } from '../user-repository';
import { Database } from '../../infrastructure/database';

describe('UserRepository Integration', () => {
  let repository: UserRepository;
  let db: Database;

  beforeAll(async () => {
    db = new Database(process.env.TEST_DATABASE_URL);
    await db.connect();
    repository = new UserRepository(db);
  });

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

  beforeEach(async () => {
    await db.query('TRUNCATE users CASCADE');
  });

  it('should create and retrieve user', async () => {
    const userData = {
      email: '[email protected]',
      name: 'Test User',
      passwordHash: 'hashedpassword123',
    };

    const userId = await repository.create(userData);
    const user = await repository.findById(userId);

    expect(user).toBeDefined();
    expect(user?.email).toBe(userData.email);
    expect(user?.name).toBe(userData.name);
  });

  it('should enforce unique email constraint', async () => {
    const userData = {
      email: '[email protected]',
      name: 'Test User',
      passwordHash: 'hashedpassword123',
    };

    await repository.create(userData);

    await expect(repository.create(userData)).rejects.toThrow(
      'Email already exists'
    );
  });
});

3. API Testing

Testing HTTP endpoints and API contracts.

4. End-to-End Testing

Testing complete user workflows through the entire system.

5. Performance Testing

Testing system behavior under load.

6. Contract Testing

Testing API contracts between services.

7. Security Testing

Testing for vulnerabilities and security issues.

We'll dive deep into each type in subsequent parts of this series.

Testing Frameworks for TypeScript

Jest

My go-to testing framework for TypeScript projects:

Installation:

npm install --save-dev jest @types/jest ts-jest

Configuration (jest.config.js):

module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  roots: ['<rootDir>/src'],
  testMatch: ['**/__tests__/**/*.test.ts'],
  collectCoverageFrom: [
    'src/**/*.ts',
    '!src/**/*.d.ts',
    '!src/**/__tests__/**',
  ],
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: 80,
    },
  },
};

Other Popular Frameworks

• Vitest: Faster alternative to Jest, great for Vite projects

• Mocha + Chai: Flexible and widely adopted

• AVA: Minimal and concurrent test runner

I chose Jest because:

• Built-in mocking capabilities

• Excellent TypeScript support

• Snapshot testing

• Great developer experience

• Large ecosystem

Test Structure Best Practices

The AAA Pattern

Every test should follow Arrange-Act-Assert:

it('should calculate order total correctly', () => {
  // Arrange: Set up test data
  const order = new Order();
  order.addItem({ name: 'Widget', price: 10.00, quantity: 2 });
  order.addItem({ name: 'Gadget', price: 15.00, quantity: 1 });

  // Act: Execute the code being tested
  const total = order.calculateTotal();

  // Assert: Verify the result
  expect(total).toBe(35.00);
});

Descriptive Test Names

Bad:

it('test1', () => { ... });
it('works', () => { ... });

Good:

it('should throw error when email is invalid', () => { ... });
it('should return 404 when user not found', () => { ... });
it('should calculate discount correctly for premium users', () => { ... });

My naming convention: should [expected behavior] when [condition]

One Assertion Per Test?

This is debatable. I prefer: test one behavior, but use multiple assertions if needed.

// Good: Testing one behavior with related assertions
it('should create user with correct attributes', async () => {
  const user = await createUser({
    email: '[email protected]',
    name: 'Test User',
  });

  expect(user.id).toBeDefined();
  expect(user.email).toBe('[email protected]');
  expect(user.name).toBe('Test User');
  expect(user.createdAt).toBeInstanceOf(Date);
});

// Bad: Testing multiple behaviors
it('should handle user operations', async () => {
  const user = await createUser({ email: '[email protected]' });
  expect(user).toBeDefined();

  const updated = await updateUser(user.id, { name: 'New Name' });
  expect(updated.name).toBe('New Name');

  await deleteUser(user.id);
  const deleted = await findUser(user.id);
  expect(deleted).toBeNull();
});

Test Organization

Project Structure

src/
├── services/
│   ├── order-service.ts
│   └── __tests__/
│       ├── order-service.test.ts           # Unit tests
│       └── order-service.integration.test.ts # Integration tests
├── repositories/
│   ├── order-repository.ts
│   └── __tests__/
│       └── order-repository.integration.test.ts
└── api/
    ├── order-controller.ts
    └── __tests__/
        ├── order-controller.test.ts
        └── order-controller.e2e.test.ts

Naming Conventions

I use clear suffixes:

• *.test.ts - Unit tests

• *.integration.test.ts - Integration tests

• *.e2e.test.ts - End-to-end tests

This makes it easy to run specific test types:

# Run only unit tests
npm test -- --testPathPattern="test.ts$"

# Run only integration tests
npm test -- --testPathPattern="integration.test.ts$"

# Run all tests for order service
npm test -- order-service

Test Coverage

Coverage measures which code lines are executed during tests.

Understanding Coverage Metrics

// Example function
export function calculateDiscount(price: number, userType: string): number {
  if (price < 0) {
    throw new Error('Price cannot be negative');
  }

  if (userType === 'premium') {
    return price * 0.2; // 20% discount
  } else if (userType === 'regular') {
    return price * 0.1; // 10% discount
  }

  return 0; // No discount
}

Low coverage test (only 60% coverage):

it('should calculate premium discount', () => {
  expect(calculateDiscount(100, 'premium')).toBe(20);
});

High coverage test (100% coverage):

describe('calculateDiscount', () => {
  it('should calculate premium discount', () => {
    expect(calculateDiscount(100, 'premium')).toBe(20);
  });

  it('should calculate regular discount', () => {
    expect(calculateDiscount(100, 'regular')).toBe(10);
  });

  it('should return zero for unknown user type', () => {
    expect(calculateDiscount(100, 'guest')).toBe(0);
  });

  it('should throw error for negative price', () => {
    expect(() => calculateDiscount(-10, 'premium')).toThrow(
      'Price cannot be negative'
    );
  });
});

Coverage Targets

In my projects:

• Unit tests: Aim for 80-90% coverage

• Integration tests: Focus on critical paths

• E2E tests: Cover main user journeys

Important: 100% coverage doesn't mean bug-free. Test quality matters more than coverage percentage.

Viewing Coverage Reports

npm test -- --coverage

Output:

----------------------|---------|----------|---------|---------|
File                  | % Stmts | % Branch | % Funcs | % Lines |
----------------------|---------|----------|---------|---------|
All files            |   84.32 |    78.56 |   86.21 |   84.32 |
 order-service.ts    |   92.15 |    87.50 |   95.00 |   92.15 |
 user-service.ts     |   78.23 |    71.42 |   80.00 |   78.23 |
----------------------|---------|----------|---------|---------|

Common Testing Mistakes

From my experience, avoid these:

1. Testing Implementation Details

Bad:

it('should call database.query with correct SQL', async () => {
  const spy = jest.spyOn(database, 'query');
  await userService.createUser({ email: '[email protected]' });
  
  expect(spy).toHaveBeenCalledWith(
    'INSERT INTO users (email) VALUES ($1)',
    ['[email protected]']
  );
});

Good:

it('should create user in database', async () => {
  const user = await userService.createUser({ email: '[email protected]' });
  
  expect(user.id).toBeDefined();
  expect(user.email).toBe('[email protected]');
  
  const savedUser = await userService.findById(user.id);
  expect(savedUser).toBeDefined();
});

2. Dependent Tests

Bad:

let userId: string;

it('should create user', async () => {
  const user = await createUser({ email: '[email protected]' });
  userId = user.id;
  expect(user).toBeDefined();
});

it('should update user', async () => {
  // Depends on previous test!
  const updated = await updateUser(userId, { name: 'New Name' });
  expect(updated.name).toBe('New Name');
});

Good:

describe('User operations', () => {
  it('should create user', async () => {
    const user = await createUser({ email: '[email protected]' });
    expect(user.id).toBeDefined();
  });

  it('should update user', async () => {
    // Independent test
    const user = await createUser({ email: '[email protected]' });
    const updated = await updateUser(user.id, { name: 'New Name' });
    expect(updated.name).toBe('New Name');
  });
});

3. Ignoring Test Failures

Never commit code with failing tests. If a test is flaky:

• Fix the flakiness (usually timing issues)

• Make it deterministic

• Don't just skip or comment it out

4. Not Testing Error Cases

Many developers only test the happy path. I always test:

• Invalid inputs

• Missing data

• Network failures

• Database errors

• Edge cases

Key Takeaways

1. Testing is not optional - It's fundamental to professional software development

2. Follow the testing pyramid - Lots of unit tests, some integration tests, few E2E tests

3. Use AAA pattern - Arrange, Act, Assert keeps tests clear

4. Test behavior, not implementation - Tests should survive refactoring

5. Keep tests independent - Each test should run in isolation

6. Coverage is a guide, not a goal - Quality over quantity

7. Test error cases - Don't just test happy paths

What's Next?

In Part 2: Unit Testing with TypeScript, we'll dive deep into:

• Writing effective unit tests

• Mocking and stubbing dependencies

• Testing async code

• Test-driven development (TDD)

• Practical examples from real microservices

---

This article is part of the Software Testing 101 series.