API Testing Skill
Expert testing for FastAPI backends and React/Next.js frontends with unit, integration, and E2E test patterns.
Quick Reference
| Test Type |
Tool |
Purpose |
Scope |
| Unit |
pytest |
Pure functions, services |
Isolated |
| Integration |
pytest + TestClient |
DB + auth + routes |
Combined |
| E2E |
Playwright/Cypress |
Browser flows |
Full stack |
Project Structure
backend/
├── tests/
│ ├── __init__.py
│ ├── conftest.py # Shared fixtures
│ ├── unit/
│ │ ├── test_services.py # Business logic tests
│ │ └── test_utils.py # Utility function tests
│ ├── integration/
│ │ ├── test_students.py # Student API tests
│ │ ├── test_fees.py # Fee API tests
│ │ └── test_auth.py # Authentication tests
│ └── fixtures/
│ ├── students.json # Test data
│ └── users.json
frontend/
├── e2e/
│ ├── specs/
│ │ ├── student.spec.ts
│ │ └── fee.spec.ts
│ ├── pages/
│ │ ├── DashboardPage.ts
│ │ └── StudentPage.ts
│ └── utils/
│ └── test-data.ts
└── playwright.config.ts
Backend: Pytest Setup
conftest.py (Shared Fixtures)
# backend/tests/conftest.py
import pytest
from typing import Generator
from fastapi.testclient import TestClient
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from sqlalchemy.pool import StaticPool
from app.main import app
from app.db.database import get_db, Base
from app.models import User, Student
from app.auth.jwt import create_access_token
from passlib.context import CryptContext
# Test database setup
SQLALCHEMY_DATABASE_URL = "sqlite:///:memory:"
engine = create_engine(
SQLALCHEMY_DATABASE_URL,
connect_args={"check_same_thread": False},
poolclass=StaticPool,
)
TestingSessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
@pytest.fixture(scope="function")
def db_session():
"""Create a fresh database for each test."""
Base.metadata.create_all(bind=engine)
session = TestingSessionLocal()
try:
yield session
finally:
session.close()
Base.metadata.drop_all(bind=engine)
@pytest.fixture(scope="function")
def client(db_session):
"""Create a test client with database override."""
def override_get_db():
try:
yield db_session
finally:
pass
app.dependency_overrides[get_db] = override_get_db
with TestClient(app) as test_client:
yield test_client
app.dependency_overrides.clear()
@pytest.fixture
def test_user(db_session):
"""Create a test user."""
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
hashed_password = pwd_context.hash("testpassword123")
user = User(
email="test@example.com",
hashed_password=hashed_password,
full_name="Test User",
is_active=True,
)
db_session.add(user)
db_session.commit()
db_session.refresh(user)
return user
@pytest.fixture
def auth_token(test_user):
"""Generate JWT token for test user."""
return create_access_token(data={"sub": test_user.email, "roles": ["admin"]})
@pytest.fixture
def auth_headers(auth_token):
"""Headers with authentication token."""
return {"Authorization": f"Bearer {auth_token}"}
Unit Tests (Pure Functions)
# backend/tests/unit/test_services.py
import pytest
from app.services.fee_calculator import calculate_fee, FeeCalculationError
class TestCalculateFee:
"""Unit tests for fee calculation logic."""
def test_basic_fee_calculation(self):
"""Test basic fee calculation without discounts."""
result = calculate_fee(
base_amount=1000.00,
grade_level=9,
has_sibling_discount=False,
is_new_student=False,
)
assert result == 1000.00
def test_sibling_discount(self):
"""Test 10% sibling discount."""
result = calculate_fee(
base_amount=1000.00,
grade_level=9,
has_sibling_discount=True,
is_new_student=False,
)
assert result == 900.00
def test_new_student_discount(self):
"""Test 15% new student discount."""
result = calculate_fee(
base_amount=1000.00,
grade_level=9,
has_sibling_discount=False,
is_new_student=True,
)
assert result == 850.00
def test_combined_discounts(self):
"""Test combined sibling and new student discounts."""
result = calculate_fee(
base_amount=1000.00,
grade_level=9,
has_sibling_discount=True,
is_new_student=True,
)
# 10% + 15% = 25% discount
assert result == 750.00
def test_invalid_base_amount(self):
"""Test that negative amounts raise error."""
with pytest.raises(FeeCalculationError):
calculate_fee(
base_amount=-100.00,
grade_level=9,
has_sibling_discount=False,
is_new_student=False,
)
def test_grade_level_multipliers(self):
"""Test different grade level multipliers."""
# Elementary (1-5): 1.0x
assert calculate_fee(1000.00, grade_level=3) == 1000.00
# Middle (6-8): 1.1x
assert calculate_fee(1000.00, grade_level=7) == 1100.00
# High (9-12): 1.2x
assert calculate_fee(1000.00, grade_level=10) == 1200.00
Integration Tests (API Endpoints)
# backend/tests/integration/test_students.py
import pytest
from fastapi import status
class TestStudentEndpoints:
"""Integration tests for student CRUD endpoints."""
@pytest.fixture
def create_student_payload(self):
"""Sample student creation payload."""
return {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@test.edu",
"date_of_birth": "2008-05-15T00:00:00Z",
"grade_level": 9,
}
def test_create_student_success(self, client, auth_headers, create_student_payload):
"""Test successful student creation."""
response = client.post(
"/api/v1/students/",
json=create_student_payload,
headers=auth_headers,
)
assert response.status_code == status.HTTP_201_CREATED
data = response.json()
assert data["first_name"] == "John"
assert data["last_name"] == "Doe"
assert "id" in data
assert data["is_active"] is True
def test_create_student_unauthorized(self, client, create_student_payload):
"""Test that unauthenticated requests are rejected."""
response = client.post(
"/api/v1/students/",
json=create_student_payload,
)
assert response.status_code == status.HTTP_401_UNAUTHORIZED
def test_create_student_invalid_email(self, client, auth_headers, create_student_payload):
"""Test validation error for invalid email."""
payload = {**create_student_payload, "email": "invalid-email"}
response = client.post(
"/api/v1/students/",
json=payload,
headers=auth_headers,
)
assert response.status_code == status.HTTP_422_UNPROCESSABLE_ENTITY
def test_create_student_missing_required_field(self, client, auth_headers):
"""Test validation error for missing required field."""
payload = {
"first_name": "John",
# Missing last_name, email, date_of_birth, grade_level
}
response = client.post(
"/api/v1/students/",
json=payload,
headers=auth_headers,
)
assert response.status_code == status.HTTP_422_UNPROCESSABLE_ENTITY
def test_get_student_success(self, client, auth_headers, create_student_payload):
"""Test retrieving a student by ID."""
# Create student first
create_response = client.post(
"/api/v1/students/",
json=create_student_payload,
headers=auth_headers,
)
student_id = create_response.json()["id"]
# Retrieve student
response = client.get(
f"/api/v1/students/{student_id}",
headers=auth_headers,
)
assert response.status_code == status.HTTP_200_OK
assert response.json()["id"] == student_id
def test_get_student_not_found(self, client, auth_headers):
"""Test 404 for non-existent student."""
response = client.get(
"/api/v1/students/99999",
headers=auth_headers,
)
assert response.status_code == status.HTTP_404_NOT_FOUND
def test_list_students_pagination(self, client, auth_headers, db_session):
"""Test student list with pagination."""
# Create multiple students
for i in range(5):
payload = {
"first_name": f"Student{i}",
"last_name": "Test",
"email": f"student{i}@test.edu",
"date_of_birth": "2008-05-15T00:00:00Z",
"grade_level": 9,
}
client.post("/api/v1/students/", json=payload, headers=auth_headers)
# Get first page
response = client.get(
"/api/v1/students/?skip=0&limit=3",
headers=auth_headers,
)
assert response.status_code == status.HTTP_200_OK
data = response.json()
assert len(data["data"]) == 3
assert data["total"] == 5
assert data["has_more"] is True
def test_update_student(self, client, auth_headers, create_student_payload):
"""Test partial update of student."""
# Create student
create_response = client.post(
"/api/v1/students/",
json=create_student_payload,
headers=auth_headers,
)
student_id = create_response.json()["id"]
# Update student
update_payload = {"first_name": "Jane", "grade_level": 10}
response = client.patch(
f"/api/v1/students/{student_id}",
json=update_payload,
headers=auth_headers,
)
assert response.status_code == status.HTTP_200_OK
data = response.json()
assert data["first_name"] == "Jane"
assert data["grade_level"] == 10
def test_delete_student(self, client, auth_headers, create_student_payload):
"""Test soft delete of student."""
# Create student
create_response = client.post(
"/api/v1/students/",
json=create_student_payload,
headers=auth_headers,
)
student_id = create_response.json()["id"]
# Delete student
response = client.delete(
f"/api/v1/students/{student_id}",
headers=auth_headers,
)
assert response.status_code == status.HTTP_204_NO_CONTENT
# Verify student is not in active list
list_response = client.get(
"/api/v1/students/",
headers=auth_headers,
)
student_ids = [s["id"] for s in list_response.json()["data"]]
assert student_id not in student_ids
Test Fixtures (JSON Data)
// backend/tests/fixtures/students.json
{
"valid_student": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@test.edu",
"date_of_birth": "2008-05-15T00:00:00Z",
"grade_level": 9
},
"invalid_students": [
{
"description": "Missing first_name",
"data": {
"last_name": "Doe",
"email": "test@test.edu",
"date_of_birth": "2008-05-15T00:00:00Z",
"grade_level": 9
}
},
{
"description": "Invalid email format",
"data": {
"first_name": "John",
"last_name": "Doe",
"email": "not-an-email",
"date_of_birth": "2008-05-15T00:00:00Z",
"grade_level": 9
}
},
{
"description": "Grade level out of range",
"data": {
"first_name": "John",
"last_name": "Doe",
"email": "test@test.edu",
"date_of_birth": "2008-05-15T00:00:00Z",
"grade_level": 15
}
}
]
}
Frontend: E2E Tests (Playwright)
playwright.config.ts
// frontend/playwright.config.ts
import { defineConfig, devices } from "@playwright/test";
export default defineConfig({
testDir: "./e2e/specs",
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,
reporter: "html",
use: {
baseURL: "http://localhost:3000",
trace: "on-first-retry",
},
projects: [
{
name: "chromium",
use: { ...devices["Desktop Chrome"] },
},
{
name: "firefox",
use: { ...devices["Desktop Firefox"] },
},
{
name: "webkit",
use: { ...devices["Desktop Safari"] },
},
],
webServer: {
command: "npm run dev",
url: "http://localhost:3000",
reuseExistingServer: !process.env.CI,
},
});
E2E Test Specification
// frontend/e2e/specs/student.spec.ts
import { test, expect } from "@playwright/test";
test.describe("Student Management", () => {
test.beforeEach(async ({ page }) => {
// Navigate to login page
await page.goto("/login");
// Login as admin
await page.fill('input[name="email"]', "admin@test.edu");
await page.fill('input[name="password"]', "adminpassword");
await page.click('button[type="submit"]');
// Verify login success
await expect(page).toHaveURL(/\/dashboard/);
await expect(page.locator("text=Admin")).toBeVisible();
});
test("should create a new student successfully", async ({ page }) => {
// Navigate to students page
await page.click('a[href="/students"]');
await expect(page).toHaveURL(/\/students/);
// Click add student button
await page.click('button:has-text("Add Student")');
// Fill in student form
await page.fill('input[name="firstName"]', "John");
await page.fill('input[name="lastName"]', "Doe");
await page.fill('input[name="email"]', "john.doe@test.edu");
await page.fill('input[name="dateOfBirth"]', "2008-05-15");
// Select grade level
await page.selectOption('select[name="gradeLevel"]', "9");
// Submit form
await page.click('button:has-text("Create")');
// Verify student was created
await expect(page.locator("text=Student created successfully")).toBeVisible();
// Verify student appears in list
await expect(page.locator("text=John Doe")).toBeVisible();
});
test("should show validation errors for invalid input", async ({ page }) => {
await page.click('a[href="/students"]');
await page.click('button:has-text("Add Student")');
// Submit empty form
await page.click('button:has-text("Create")');
// Verify validation errors
await expect(page.locator("text=First name is required")).toBeVisible();
await expect(page.locator("text=Last name is required")).toBeVisible();
await expect(page.locator("text=Invalid email address")).toBeVisible();
});
test("should filter students by grade level", async ({ page }) => {
await page.click('a[href="/students"]');
// Filter by grade 9
await page.selectOption('select[name="gradeFilter"]', "9");
await page.click('button:has-text("Apply")');
// Verify only grade 9 students shown
const rows = page.locator("table.student-list tbody tr");
await expect(rows).toHaveCount(3); // Assuming 3 grade 9 students
});
test("should view student details", async ({ page }) => {
await page.click('a[href="/students"]');
// Click on first student
await page.click('table.student-list tbody tr:first-child a');
// Verify details page
await expect(page).toHaveURL(/\/students\/\d+/);
await expect(page.locator("h1")).toContainText("Student Details");
});
});
Page Object Model
// frontend/e2e/pages/StudentsPage.ts
import { Page, Locator, expect } from "@playwright/test";
export class StudentsPage {
readonly page: Page;
readonly addButton: Locator;
readonly studentTable: Locator;
readonly gradeFilter: Locator;
readonly searchInput: Locator;
constructor(page: Page) {
this.page = page;
this.addButton = page.locator('button:has-text("Add Student")');
this.studentTable = page.locator("table.student-list");
this.gradeFilter = page.locator('select[name="gradeFilter"]');
this.searchInput = page.locator('input[name="search"]');
}
async goto() {
await this.page.goto("/students");
}
async createStudent(data: {
firstName: string;
lastName: string;
email: string;
gradeLevel: string;
dateOfBirth?: string;
}) {
await this.addButton.click();
await this.page.fill('input[name="firstName"]', data.firstName);
await this.page.fill('input[name="lastName"]', data.lastName);
await this.page.fill('input[name="email"]', data.email);
await this.page.selectOption('select[name="gradeLevel"]', data.gradeLevel);
if (data.dateOfBirth) {
await this.page.fill('input[name="dateOfBirth"]', data.dateOfBirth);
}
await this.page.click('button:has-text("Create")');
}
async getStudentNames(): Promise<string[]> {
const rows = this.studentTable.locator("tbody tr");
const names: string[] = [];
for (const row of await rows.all()) {
names.push(await row.locator("td:first-child").textContent());
}
return names;
}
async filterByGrade(grade: string) {
await this.gradeFilter.selectOption(grade);
await this.page.click('button:has-text("Apply")');
}
async searchByName(name: string) {
await this.searchInput.fill(name);
await this.page.keyboard.press("Enter");
}
}
Test Pyramid
/\
/ \ E2E Tests (10%)
/ \ - Critical user journeys
/______\
/ \
/ \ Integration Tests (30%)
/ \ - API endpoints with DB
/______________\
/ \
/ \ Unit Tests (60%)
/ \ - Services, utilities
/______________________\
Quality Checklist
Running Tests
# Backend tests
pytest # Run all tests
pytest tests/unit/ # Unit tests only
pytest tests/integration/ # Integration tests only
pytest -v # Verbose output
pytest --cov=app # With coverage
# Frontend E2E tests
npx playwright install # Install browsers
npx playwright test # Run E2E tests
npx playwright test --reporter=line
CI Configuration
# .github/workflows/test.yml
name: Tests
on: [push, pull_request]
jobs:
test-backend:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.11"
- run: pip install -r requirements.txt
- run: pip install pytest pytest-cov
- run: pytest --cov=app --cov-report=xml
- uses: codecov/codecov-action@v3
test-frontend:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "20"
- run: npm ci
- run: npm run test
- run: npm run build
Integration Points
| Skill |
Integration |
@sqlmodel-crud |
Test CRUD operations with test database |
@jwt-auth |
Test authenticated endpoints with test tokens |
@api-route-design |
Test all CRUD routes with various status codes |
@error-handling |
Test error responses and edge cases |
@data-validation |
Test validation error messages |
aiskillstore