Part 4: API Testing and Contract Testing

Introduction

API testing ensures your HTTP endpoints behave correctly—proper status codes, valid responses, correct error handling, and consistent contracts. In my microservices architecture, APIs are the integration points between services, making API testing critical for system reliability.

This part covers practical API testing techniques I use in production TypeScript microservices, including REST API testing, authentication, and contract testing between services.

REST API Testing Fundamentals

Example: User Management API

user-controller.ts:

// src/api/user-controller.ts
import { Request, Response, NextFunction } from 'express';
import { UserService } from '../services/user-service';
import { z } from 'zod';

const CreateUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2).max(100),
  password: z.string().min(8),
});

export class UserController {
  constructor(private readonly userService: UserService) {}

  async createUser(req: Request, res: Response, next: NextFunction) {
    try {
      const validation = CreateUserSchema.safeParse(req.body);
      
      if (!validation.success) {
        return res.status(400).json({
          error: 'Validation failed',
          details: validation.error.errors,
        });
      }

      const user = await this.userService.createUser(validation.data);
      
      return res.status(201).json({
        id: user.id,
        email: user.email,
        name: user.name,
        createdAt: user.createdAt,
      });
    } catch (error) {
      if (error instanceof Error) {
        if (error.message.includes('already exists')) {
          return res.status(409).json({ error: error.message });
        }
      }
      next(error);
    }
  }

  async getUser(req: Request, res: Response, next: NextFunction) {
    try {
      const { id } = req.params;
      const user = await this.userService.getUserById(id);
      
      return res.status(200).json({
        id: user.id,
        email: user.email,
        name: user.name,
        createdAt: user.createdAt,
      });
    } catch (error) {
      if (error instanceof Error && error.message.includes('not found')) {
        return res.status(404).json({ error: error.message });
      }
      next(error);
    }
  }

  async updateUser(req: Request, res: Response, next: NextFunction) {
    try {
      const { id } = req.params;
      const { name } = req.body;
      
      const user = await this.userService.updateUser(id, { name });
      
      return res.status(200).json({
        id: user.id,
        email: user.email,
        name: user.name,
        updatedAt: user.updatedAt,
      });
    } catch (error) {
      next(error);
    }
  }

  async deleteUser(req: Request, res: Response, next: NextFunction) {
    try {
      const { id } = req.params;
      await this.userService.deleteUser(id);
      
      return res.status(204).send();
    } catch (error) {
      next(error);
    }
  }
}

Setting Up Test Server

test-server.ts:

// src/test-helpers/test-server.ts
import express, { Express } from 'express';
import { UserController } from '../api/user-controller';
import { UserService } from '../services/user-service';
import { IUserRepository } from '../repositories/user-repository';

export function createTestServer(userRepository: IUserRepository): Express {
  const app = express();
  
  app.use(express.json());
  
  const userService = new UserService(userRepository);
  const userController = new UserController(userService);
  
  // Routes
  app.post('/api/users', (req, res, next) => 
    userController.createUser(req, res, next)
  );
  
  app.get('/api/users/:id', (req, res, next) => 
    userController.getUser(req, res, next)
  );
  
  app.put('/api/users/:id', (req, res, next) => 
    userController.updateUser(req, res, next)
  );
  
  app.delete('/api/users/:id', (req, res, next) => 
    userController.deleteUser(req, res, next)
  );
  
  // Error handler
  app.use((err: Error, req: express.Request, res: express.Response, next: express.NextFunction) => {
    console.error(err);
    res.status(500).json({ error: 'Internal server error' });
  });
  
  return app;
}

API Tests with Supertest

Installation:

npm install --save-dev supertest @types/supertest

user-api.test.ts:

// src/api/__tests__/user-api.test.ts
import request from 'supertest';
import { Express } from 'express';
import { createTestServer } from '../../test-helpers/test-server';
import { IUserRepository, User } from '../../repositories/user-repository';

describe('User API', () => {
  let app: Express;
  let mockRepository: jest.Mocked<IUserRepository>;

  beforeEach(() => {
    mockRepository = {
      save: jest.fn(),
      findById: jest.fn(),
      findByEmail: jest.fn(),
      update: jest.fn(),
      delete: jest.fn(),
    };

    app = createTestServer(mockRepository);
  });

  describe('POST /api/users', () => {
    it('should create user with valid data', async () => {
      const newUser: User = {
        id: '123',
        email: '[email protected]',
        name: 'Test User',
        passwordHash: 'hashed',
        createdAt: new Date(),
        updatedAt: new Date(),
      };

      mockRepository.findByEmail.mockResolvedValue(null);
      mockRepository.save.mockResolvedValue();

      const response = await request(app)
        .post('/api/users')
        .send({
          email: '[email protected]',
          name: 'Test User',
          password: 'SecureP@ss123',
        })
        .expect(201)
        .expect('Content-Type', /json/);

      expect(response.body).toMatchObject({
        email: '[email protected]',
        name: 'Test User',
      });
      expect(response.body.id).toBeDefined();
      expect(response.body.createdAt).toBeDefined();
      expect(response.body.password).toBeUndefined(); // Should not return password
    });

    it('should return 400 for invalid email', async () => {
      const response = await request(app)
        .post('/api/users')
        .send({
          email: 'invalid-email',
          name: 'Test User',
          password: 'SecureP@ss123',
        })
        .expect(400);

      expect(response.body.error).toBe('Validation failed');
      expect(response.body.details).toBeDefined();
    });

    it('should return 400 for short password', async () => {
      const response = await request(app)
        .post('/api/users')
        .send({
          email: '[email protected]',
          name: 'Test User',
          password: 'short',
        })
        .expect(400);

      expect(response.body.error).toBe('Validation failed');
    });

    it('should return 409 for duplicate email', async () => {
      const existingUser: User = {
        id: '999',
        email: '[email protected]',
        name: 'Existing User',
        passwordHash: 'hashed',
        createdAt: new Date(),
        updatedAt: new Date(),
      };

      mockRepository.findByEmail.mockResolvedValue(existingUser);

      const response = await request(app)
        .post('/api/users')
        .send({
          email: '[email protected]',
          name: 'Test User',
          password: 'SecureP@ss123',
        })
        .expect(409);

      expect(response.body.error).toContain('already exists');
    });

    it('should return 400 for missing fields', async () => {
      await request(app)
        .post('/api/users')
        .send({
          email: '[email protected]',
          // Missing name and password
        })
        .expect(400);
    });
  });

  describe('GET /api/users/:id', () => {
    it('should return user by id', async () => {
      const user: User = {
        id: '123',
        email: '[email protected]',
        name: 'Test User',
        passwordHash: 'hashed',
        createdAt: new Date('2024-01-01'),
        updatedAt: new Date('2024-01-01'),
      };

      mockRepository.findById.mockResolvedValue(user);

      const response = await request(app)
        .get('/api/users/123')
        .expect(200);

      expect(response.body).toMatchObject({
        id: '123',
        email: '[email protected]',
        name: 'Test User',
      });
      expect(response.body.passwordHash).toBeUndefined();
    });

    it('should return 404 for non-existent user', async () => {
      mockRepository.findById.mockRejectedValue(
        new Error('User not found: 999')
      );

      const response = await request(app)
        .get('/api/users/999')
        .expect(404);

      expect(response.body.error).toContain('not found');
    });
  });

  describe('PUT /api/users/:id', () => {
    it('should update user', async () => {
      const updatedUser: User = {
        id: '123',
        email: '[email protected]',
        name: 'Updated Name',
        passwordHash: 'hashed',
        createdAt: new Date('2024-01-01'),
        updatedAt: new Date('2024-01-15'),
      };

      mockRepository.update.mockResolvedValue(updatedUser);

      const response = await request(app)
        .put('/api/users/123')
        .send({ name: 'Updated Name' })
        .expect(200);

      expect(response.body.name).toBe('Updated Name');
      expect(response.body.updatedAt).toBeDefined();
    });
  });

  describe('DELETE /api/users/:id', () => {
    it('should delete user', async () => {
      mockRepository.delete.mockResolvedValue();

      await request(app)
        .delete('/api/users/123')
        .expect(204);
    });
  });
});

Testing Authentication

JWT Authentication Middleware

auth-middleware.ts:

// src/middleware/auth-middleware.ts
import { Request, Response, NextFunction } from 'express';
import jwt from 'jsonwebtoken';

export interface JwtPayload {
  userId: string;
  email: string;
}

export interface AuthRequest extends Request {
  user?: JwtPayload;
}

export class AuthMiddleware {
  constructor(private readonly jwtSecret: string) {}

  authenticate(req: AuthRequest, res: Response, next: NextFunction) {
    const authHeader = req.headers.authorization;

    if (!authHeader || !authHeader.startsWith('Bearer ')) {
      return res.status(401).json({ error: 'Unauthorized' });
    }

    const token = authHeader.substring(7);

    try {
      const payload = jwt.verify(token, this.jwtSecret) as JwtPayload;
      req.user = payload;
      next();
    } catch (error) {
      return res.status(401).json({ error: 'Invalid token' });
    }
  }
}

Testing authentication:

// src/middleware/__tests__/auth-middleware.test.ts
import request from 'supertest';
import express, { Express } from 'express';
import jwt from 'jsonwebtoken';
import { AuthMiddleware } from '../auth-middleware';

describe('Auth Middleware', () => {
  let app: Express;
  const JWT_SECRET = 'test-secret';
  let authMiddleware: AuthMiddleware;

  beforeEach(() => {
    app = express();
    authMiddleware = new AuthMiddleware(JWT_SECRET);

    app.get('/protected', 
      authMiddleware.authenticate.bind(authMiddleware),
      (req: any, res) => {
        res.json({ 
          message: 'Success',
          userId: req.user.userId 
        });
      }
    );
  });

  it('should allow access with valid token', async () => {
    const token = jwt.sign(
      { userId: '123', email: '[email protected]' },
      JWT_SECRET,
      { expiresIn: '1h' }
    );

    const response = await request(app)
      .get('/protected')
      .set('Authorization', `Bearer ${token}`)
      .expect(200);

    expect(response.body.message).toBe('Success');
    expect(response.body.userId).toBe('123');
  });

  it('should reject request without token', async () => {
    await request(app)
      .get('/protected')
      .expect(401);
  });

  it('should reject request with invalid token', async () => {
    await request(app)
      .get('/protected')
      .set('Authorization', 'Bearer invalid-token')
      .expect(401);
  });

  it('should reject expired token', async () => {
    const token = jwt.sign(
      { userId: '123', email: '[email protected]' },
      JWT_SECRET,
      { expiresIn: '-1h' } // Expired 1 hour ago
    );

    await request(app)
      .get('/protected')
      .set('Authorization', `Bearer ${token}`)
      .expect(401);
  });

  it('should reject token with wrong secret', async () => {
    const token = jwt.sign(
      { userId: '123', email: '[email protected]' },
      'wrong-secret',
      { expiresIn: '1h' }
    );

    await request(app)
      .get('/protected')
      .set('Authorization', `Bearer ${token}`)
      .expect(401);
  });
});

OpenAPI/Swagger Validation

Testing that your API matches its OpenAPI specification.

Installation:

npm install --save-dev jest-openapi

openapi.yaml:

# api-docs/openapi.yaml
openapi: 3.0.0
info:
  title: User API
  version: 1.0.0

paths:
  /api/users:
    post:
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - name
                - password
              properties:
                email:
                  type: string
                  format: email
                name:
                  type: string
                  minLength: 2
                password:
                  type: string
                  minLength: 8
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  email:
                    type: string
                  name:
                    type: string
                  createdAt:
                    type: string
                    format: date-time
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  details:
                    type: array

  /api/users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  email:
                    type: string
                  name:
                    type: string
        '404':
          description: User not found

OpenAPI validation tests:

// src/api/__tests__/user-api-openapi.test.ts
import request from 'supertest';
import path from 'path';
import jestOpenAPI from 'jest-openapi';
import { createTestServer } from '../../test-helpers/test-server';

// Load OpenAPI spec
const openApiPath = path.join(__dirname, '../../../api-docs/openapi.yaml');
jestOpenAPI(openApiPath);

describe('User API OpenAPI Compliance', () => {
  let app: any;

  beforeEach(() => {
    const mockRepository = {
      save: jest.fn(),
      findById: jest.fn(),
      findByEmail: jest.fn(),
      update: jest.fn(),
      delete: jest.fn(),
    };
    app = createTestServer(mockRepository);
  });

  it('POST /api/users should satisfy OpenAPI spec', async () => {
    const response = await request(app)
      .post('/api/users')
      .send({
        email: '[email protected]',
        name: 'Test User',
        password: 'SecureP@ss123',
      });

    expect(response).toSatisfyApiSpec();
  });

  it('GET /api/users/:id should satisfy OpenAPI spec', async () => {
    const response = await request(app)
      .get('/api/users/123');

    expect(response).toSatisfyApiSpec();
  });
});

Contract Testing with Pact

Contract testing ensures services agree on their API contracts.

Installation:

npm install --save-dev @pact-foundation/pact

Consumer Side (Order Service)

order-service-consumer.pact.test.ts:

// src/clients/__tests__/user-client.pact.test.ts
import { Pact } from '@pact-foundation/pact';
import path from 'path';
import { UserClient } from '../user-client';

describe('User Service Contract', () => {
  const provider = new Pact({
    consumer: 'OrderService',
    provider: 'UserService',
    port: 8989,
    log: path.resolve(process.cwd(), 'logs', 'pact.log'),
    dir: path.resolve(process.cwd(), 'pacts'),
    logLevel: 'warn',
  });

  beforeAll(() => provider.setup());
  afterEach(() => provider.verify());
  afterAll(() => provider.finalize());

  describe('GET /api/users/:id', () => {
    it('should return user when user exists', async () => {
      await provider.addInteraction({
        state: 'user with id 123 exists',
        uponReceiving: 'a request for user 123',
        withRequest: {
          method: 'GET',
          path: '/api/users/123',
          headers: {
            Accept: 'application/json',
          },
        },
        willRespondWith: {
          status: 200,
          headers: {
            'Content-Type': 'application/json',
          },
          body: {
            id: '123',
            email: '[email protected]',
            name: 'Test User',
            createdAt: '2024-01-01T00:00:00.000Z',
          },
        },
      });

      const client = new UserClient('http://localhost:8989');
      const user = await client.getUser('123');

      expect(user.id).toBe('123');
      expect(user.email).toBe('[email protected]');
    });

    it('should return 404 when user not found', async () => {
      await provider.addInteraction({
        state: 'user with id 999 does not exist',
        uponReceiving: 'a request for non-existent user 999',
        withRequest: {
          method: 'GET',
          path: '/api/users/999',
        },
        willRespondWith: {
          status: 404,
          headers: {
            'Content-Type': 'application/json',
          },
          body: {
            error: 'User not found: 999',
          },
        },
      });

      const client = new UserClient('http://localhost:8989');

      await expect(client.getUser('999')).rejects.toThrow('User not found');
    });
  });
});

Provider Side (User Service)

user-service-provider.pact.test.ts:

// src/api/__tests__/user-api.pact.test.ts
import path from 'path';
import { Verifier } from '@pact-foundation/pact';
import { createTestServer } from '../../test-helpers/test-server';
import { Server } from 'http';

describe('User Service Provider', () => {
  let server: Server;
  const PORT = 8990;

  beforeAll((done) => {
    const mockRepository = {
      findById: jest.fn().mockImplementation((id: string) => {
        if (id === '123') {
          return Promise.resolve({
            id: '123',
            email: '[email protected]',
            name: 'Test User',
            createdAt: new Date('2024-01-01'),
          });
        }
        throw new Error(`User not found: ${id}`);
      }),
      save: jest.fn(),
      findByEmail: jest.fn(),
      update: jest.fn(),
      delete: jest.fn(),
    };

    const app = createTestServer(mockRepository);
    server = app.listen(PORT, done);
  });

  afterAll((done) => {
    server.close(done);
  });

  it('should validate the contract', () => {
    const opts = {
      provider: 'UserService',
      providerBaseUrl: `http://localhost:${PORT}`,
      pactUrls: [
        path.resolve(process.cwd(), 'pacts', 'orderservice-userservice.json'),
      ],
      stateHandlers: {
        'user with id 123 exists': () => Promise.resolve(),
        'user with id 999 does not exist': () => Promise.resolve(),
      },
    };

    return new Verifier(opts).verifyProvider();
  });
});

Testing Rate Limiting

rate-limiter.ts:

// src/middleware/rate-limiter.ts
import rateLimit from 'express-rate-limit';

export const createRateLimiter = (windowMs: number, max: number) => {
  return rateLimit({
    windowMs,
    max,
    message: 'Too many requests, please try again later',
    standardHeaders: true,
    legacyHeaders: false,
  });
};

Testing rate limiting:

// src/middleware/__tests__/rate-limiter.test.ts
import request from 'supertest';
import express from 'express';
import { createRateLimiter } from '../rate-limiter';

describe('Rate Limiter', () => {
  let app: express.Express;

  beforeEach(() => {
    app = express();
    
    // 3 requests per minute
    const limiter = createRateLimiter(60000, 3);
    
    app.use('/api', limiter);
    app.get('/api/test', (req, res) => {
      res.json({ message: 'Success' });
    });
  });

  it('should allow requests within limit', async () => {
    await request(app).get('/api/test').expect(200);
    await request(app).get('/api/test').expect(200);
    await request(app).get('/api/test').expect(200);
  });

  it('should block requests exceeding limit', async () => {
    await request(app).get('/api/test').expect(200);
    await request(app).get('/api/test').expect(200);
    await request(app).get('/api/test').expect(200);
    
    const response = await request(app).get('/api/test').expect(429);
    
    expect(response.body.message).toContain('Too many requests');
  });

  it('should include rate limit headers', async () => {
    const response = await request(app).get('/api/test');
    
    expect(response.headers['ratelimit-limit']).toBeDefined();
    expect(response.headers['ratelimit-remaining']).toBeDefined();
  });
});

API Versioning Tests

v1 and v2 controllers:

// src/api/v1/user-controller.ts
export class UserControllerV1 {
  async getUser(req: Request, res: Response) {
    // Returns simple format
    res.json({
      id: '123',
      name: 'Test User',
    });
  }
}

// src/api/v2/user-controller.ts
export class UserControllerV2 {
  async getUser(req: Request, res: Response) {
    // Returns extended format
    res.json({
      id: '123',
      firstName: 'Test',
      lastName: 'User',
      email: '[email protected]',
    });
  }
}

Version tests:

// src/api/__tests__/versioning.test.ts
import request from 'supertest';
import express from 'express';

describe('API Versioning', () => {
  let app: express.Express;

  beforeEach(() => {
    app = express();
    
    app.get('/api/v1/users/:id', (req, res) => {
      res.json({ id: '123', name: 'Test User' });
    });
    
    app.get('/api/v2/users/:id', (req, res) => {
      res.json({
        id: '123',
        firstName: 'Test',
        lastName: 'User',
        email: '[email protected]',
      });
    });
  });

  it('should return v1 format for /api/v1/users/:id', async () => {
    const response = await request(app)
      .get('/api/v1/users/123')
      .expect(200);

    expect(response.body).toHaveProperty('name');
    expect(response.body).not.toHaveProperty('firstName');
  });

  it('should return v2 format for /api/v2/users/:id', async () => {
    const response = await request(app)
      .get('/api/v2/users/123')
      .expect(200);

    expect(response.body).toHaveProperty('firstName');
    expect(response.body).toHaveProperty('lastName');
    expect(response.body).toHaveProperty('email');
    expect(response.body).not.toHaveProperty('name');
  });
});

Best Practices

1. Test HTTP Status Codes

Always verify correct status codes:

200 - Success
201 - Created
204 - No Content
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
409 - Conflict
422 - Unprocessable Entity
429 - Too Many Requests
500 - Internal Server Error

2. Test Content-Type Headers

const response = await request(app)
  .get('/api/users/123')
  .expect('Content-Type', /json/);

3. Test Error Responses

it('should return structured error for validation failure', async () => {
  const response = await request(app)
    .post('/api/users')
    .send({ invalid: 'data' })
    .expect(400);

  expect(response.body).toHaveProperty('error');
  expect(response.body).toHaveProperty('details');
});

4. Test CORS Headers

it('should include CORS headers', async () => {
  const response = await request(app)
    .options('/api/users')
    .set('Origin', 'http://example.com')
    .expect(204);

  expect(response.headers['access-control-allow-origin']).toBeDefined();
});

Key Takeaways

Test API contracts thoroughly - Status codes, headers, response bodies
Use supertest for HTTP testing - Simple and effective
Validate against OpenAPI specs - Ensure documentation matches implementation
Contract testing prevents integration issues - Services agree on interfaces
Test authentication and authorization - Security is critical
Test rate limiting - Protect your APIs
Version your APIs - Test all supported versions

What's Next?

In Part 5: End-to-End Testing, we'll cover:

Browser automation with Playwright
Testing complete user workflows
Visual regression testing
E2E test patterns and best practices

This article is part of the Software Testing 101 series.

PreviousPart 3: Integration Testing NextPart 5: End-to-End Testing

Last updated 15 hours ago

hashtagIntroduction

hashtagREST API Testing Fundamentals

hashtagExample: User Management API

hashtagSetting Up Test Server

hashtagAPI Tests with Supertest

hashtagTesting Authentication

hashtagJWT Authentication Middleware

hashtagOpenAPI/Swagger Validation

hashtagContract Testing with Pact

hashtagConsumer Side (Order Service)

hashtagProvider Side (User Service)

hashtagTesting Rate Limiting

hashtagAPI Versioning Tests

hashtagBest Practices

hashtag1. Test HTTP Status Codes

hashtag2. Test Content-Type Headers

hashtag3. Test Error Responses

hashtag4. Test CORS Headers

hashtagKey Takeaways

hashtagWhat's Next?

Introduction

REST API Testing Fundamentals

Example: User Management API

Setting Up Test Server

API Tests with Supertest

Testing Authentication

JWT Authentication Middleware

OpenAPI/Swagger Validation

Contract Testing with Pact

Consumer Side (Order Service)

Provider Side (User Service)

Testing Rate Limiting

API Versioning Tests

Best Practices

1. Test HTTP Status Codes

2. Test Content-Type Headers

3. Test Error Responses

4. Test CORS Headers

Key Takeaways

What's Next?