API Contract Testing with OpenAPI Spec Validation

1// Install required dependencies
2// npm install --save-dev supertest @types/supertest
3
4import { Test, TestingModule } from '@nestjs/testing';
5import { INestApplication, ValidationPipe } from '@nestjs/common';
6import * as request from 'supertest';
7import { AppModule } from '../../app.module';
8
9describe('API Contract Testing with OpenAPI Spec Validation', () => {
10  let app: INestApplication;
11
12  beforeAll(async () => {
13    const module: TestingModule = await Test.createTestingModule({
14      imports: [AppModule],
15    }).compile();
16    app = module.createNestApplication();
17    app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
18    await app.init();
19  });
20
21  afterAll(() => app.close());
22
23  it('basic endpoint health check', async () => {
24    const res = await request(app.getHttpServer()).get('/api/health');
25    expect(res.status).toBe(200);
26  });
27});

1// Pattern 1: Arrange-Act-Assert
2describe('API endpoint behavior', () => {
3  it('returns correct response for valid request', async () => {
4    // Arrange
5    const token = await getAuthToken();
6    const payload = { name: 'Test Resource', value: 42 };
7
8    // Act
9    const res = await request(app.getHttpServer())
10      .post('/api/resources')
11      .set('Authorization', `Bearer ${token}`)
12      .send(payload);
13
14    // Assert
15    expect(res.status).toBe(201);
16    expect(res.body).toMatchObject({
17      id: expect.any(String),
18      name: payload.name,
19      value: payload.value,
20    });
21  });
22
23  it('handles concurrent requests correctly', async () => {
24    const requests = Array.from({ length: 10 }, () =>
25      request(app.getHttpServer()).get('/api/resources')
26    );
27    const results = await Promise.all(requests);
28    results.forEach(res => expect(res.status).toBe(200));
29  });
30});

1describe('Error handling', () => {
2  it('returns 400 for invalid input', async () => {
3    const res = await request(app.getHttpServer())
4      .post('/api/resources')
5      .send({ invalidField: 'value' });
6    expect(res.status).toBe(400);
7    expect(res.body.message).toBeDefined();
8  });
9
10  it('returns 401 without auth token', async () => {
11    const res = await request(app.getHttpServer()).post('/api/resources');
12    expect(res.status).toBe(401);
13  });
14
15  it('returns 404 for non-existent resource', async () => {
16    const res = await request(app.getHttpServer()).get('/api/resources/non-existent');
17    expect(res.status).toBe(404);
18  });
19
20  it('handles large page sizes gracefully', async () => {
21    const res = await request(app.getHttpServer()).get('/api/resources?limit=99999');
22    expect([200, 400]).toContain(res.status);
23    if (res.status === 200) {
24      expect(res.body.data.length).toBeLessThanOrEqual(100);
25    }
26  });
27});

1# .github/workflows/api-tests.yml
2name: API Integration Tests
3on: [push, pull_request]
4jobs:
5  api-tests:
6    runs-on: ubuntu-latest
7    services:
8      postgres:
9        image: postgres:16
10        env:
11          POSTGRES_PASSWORD: postgres
12          POSTGRES_DB: app_test
13        options: >-
14          --health-cmd pg_isready
15          --health-interval 10s
16          --health-timeout 5s
17          --health-retries 5
18    steps:
19      - uses: actions/checkout@v4
20      - uses: actions/setup-node@v4
21        with: { node-version: '20', cache: 'npm' }
22      - run: npm ci
23      - run: npx prisma migrate deploy
24        env:
25          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/app_test
26      - run: npm run test:api
27        env:
28          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/app_test
29          JWT_SECRET: test-secret-key-32-chars-minimum
30      - uses: actions/upload-artifact@v4
31        if: always()
32        with:
33          name: api-test-results
34          path: test-results/

1// Shared test helpers for consistent setup
2export class ApiTestHelper {
3  constructor(private readonly app: INestApplication) {}
4
5  async authenticate(email: string, password: string): Promise<string> {
6    const res = await request(this.app.getHttpServer())
7      .post('/auth/login')
8      .send({ email, password });
9    if (res.status !== 200) throw new Error('Auth failed: ' + res.status);
10    return res.body.accessToken;
11  }
12
13  async createResource(token: string, data: Record<string, unknown>) {
14    const res = await request(this.app.getHttpServer())
15      .post('/api/resources')
16      .set('Authorization', `Bearer ${token}`)
17      .send(data);
18    expect(res.status).toBe(201);
19    return res.body;
20  }
21
22  async expectPaginatedResponse(path: string, token?: string) {
23    const req = request(this.app.getHttpServer()).get(path);
24    if (token) req.set('Authorization', `Bearer ${token}`);
25    const res = await req;
26    expect(res.status).toBe(200);
27    expect(res.body).toMatchObject({
28      data: expect.any(Array),
29      meta: expect.objectContaining({ total: expect.any(Number) }),
30    });
31    return res.body;
32  }
33}