API Testing

Expert knowledge for testing HTTP APIs with Supertest (TypeScript/JavaScript) and httpx/pytest (Python).

TypeScript/JavaScript (Supertest)

Installation

Using Bun

bun add -d supertest @types/supertest

or: npm install -D supertest @types/supertest

Basic Setup

import { describe, it, expect } from 'vitest' import request from 'supertest' import { app } from './app'

describe('API Tests', () => { it('returns health status', async () => { const response = await request(app) .get('/api/health') .expect(200)

expect(response.body).toEqual({ status: 'ok' })

})

it('creates a user', async () => { const response = await request(app) .post('/api/users') .send({ name: 'John Doe', email: 'john@example.com' }) .expect(201)

expect(response.body).toMatchObject({
  id: expect.any(Number),
  name: 'John Doe',
})

})

it('validates required fields', async () => { await request(app) .post('/api/users') .send({ name: 'John Doe' }) .expect(400) }) })

Request Methods

// GET await request(app).get('/api/users').expect(200)

// POST with body await request(app) .post('/api/users') .send({ name: 'John' }) .expect(201)

// PUT await request(app) .put('/api/users/1') .send({ name: 'Jane' }) .expect(200)

// DELETE await request(app).delete('/api/users/1').expect(204)

Headers and Query Parameters

// Set headers await request(app) .get('/api/protected') .set('Authorization', 'Bearer token123') .expect(200)

// Query parameters await request(app) .get('/api/users') .query({ page: 1, limit: 10 }) .expect(200)

Authentication Testing

describe('Authentication', () => { let authToken: string

beforeAll(async () => { const response = await request(app) .post('/api/auth/login') .send({ email: 'user@example.com', password: 'password123' }) .expect(200)

authToken = response.body.token

})

it('accesses protected endpoint', async () => { await request(app) .get('/api/protected') .set('Authorization', Bearer ${authToken}) .expect(200) })

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

Error Handling

it('handles validation errors', async () => { const response = await request(app) .post('/api/users') .send({ email: 'invalid-email' }) .expect(400)

expect(response.body).toMatchObject({ error: 'Validation failed', details: expect.any(Array), }) })

it('handles not found', async () => { await request(app).get('/api/users/999999').expect(404) })

Python (httpx + pytest)

Installation

uv add --dev httpx pytest-asyncio

Basic Setup

import pytest from fastapi.testclient import TestClient from main import app

client = TestClient(app)

def test_health_check(): response = client.get("/api/health") assert response.status_code == 200 assert response.json() == {"status": "ok"}

def test_create_user(): response = client.post( "/api/users", json={"name": "John Doe", "email": "john@example.com"} ) assert response.status_code == 201 data = response.json() assert data["name"] == "John Doe" assert "id" in data

def test_not_found(): response = client.get("/api/users/999") assert response.status_code == 404

Fixtures

@pytest.fixture def auth_token(client): response = client.post( "/api/auth/login", json={"email": "user@example.com", "password": "password123"} ) return response.json()["token"]

def test_protected_endpoint(client, auth_token): response = client.get( "/api/protected", headers={"Authorization": f"Bearer {auth_token}"} ) assert response.status_code == 200

File Upload

def test_file_upload(client, tmp_path): test_file = tmp_path / "test.txt" test_file.write_text("test content")

with open(test_file, "rb") as f:
    response = client.post(
        "/api/upload",
        files={"file": ("test.txt", f, "text/plain")}
    )

assert response.status_code == 200

GraphQL Testing

it('queries GraphQL endpoint', async () => { const query = query GetUser($id: ID!) { user(id: $id) { id name email } }

const response = await request(app) .post('/graphql') .send({ query, variables: { id: '1' } }) .expect(200)

expect(response.body.data.user).toMatchObject({ id: '1', name: expect.any(String), }) })

Performance Testing

it('responds within acceptable time', async () => { const start = Date.now() await request(app).get('/api/users').expect(200) const duration = Date.now() - start expect(duration).toBeLessThan(100) // 100ms threshold })

Best Practices

• Group related endpoints in describe blocks

• Reset database between tests

• Validate status codes first

• Check response structure

• Test error message format

• Mock external services

• Test both happy path and error cases

See Also

• vitest-testing

• Unit testing framework

• playwright-testing

• E2E API testing

• test-quality-analysis

• Test quality patterns