Skip to main content
skill CX Codex

api-testing · laurigates — Claude Code skill: HTTP API testing guide

api-testing — a skill for writing REST and GraphQL API tests with Supertest (TypeScript) and httpx/pytest (Python). Validates status codes, response schemas, auth flows, and error handling.

MIT 106 installs ★ 60 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add laurigates/claude-plugins --skill api-testing -a claude-code
Open on GitHub

What api-testing does

The skill gives the agent expertise in two HTTP API testing stacks: Supertest for Node.js (Express, Fastify) and httpx with pytest for Python (FastAPI). The agent writes tests for requests and responses — checks status codes, headers, JSON schemas, validates Bearer tokens, cookies, OAuth flows. Covers error scenarios (4xx, 5xx) and integration with databases and external services.

Inside are code examples for all HTTP methods (GET, POST, PUT, PATCH, DELETE), working with headers and query params, response body assertions. For Python, shows FastAPI TestClient and async tests via pytest-asyncio; for TypeScript, Supertest paired with Vitest or Jest. The skill is invoked automatically when Supertest, httpx, REST validation, or HTTP response errors are mentioned.

Before running tests, install dependencies: for TypeScript, supertest and @types/supertest packages; for Python, httpx and pytest-asyncio. Install via npm, bun, pip, or uv depending on the project.

What it helps with

  • write Supertest tests for Express or Fastify endpoints
  • check status codes, headers, and JSON response schema
  • test authentication with Bearer tokens and cookies
  • cover 4xx and 5xx error handling in tests
  • write httpx + pytest tests for FastAPI routes

Example prompts for the agent

  • Write Supertest tests for /api/users and /api/health endpoints in Express
  • Add pytest tests for the FastAPI /api/orders route, check 201 status and response shape
  • Cover 400 and 404 error handling in /api/products/:id with tests

How to install api-testing

1Skills CLI (Vercel)

npx skills add laurigates/claude-plugins --skill api-testing -a claude-code

2Manually: put the files in place

~/.claude/skills/api-testing/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/api-testing/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about api-testing

How to install api-testing in Claude Code?

Run npx skills add laurigates/claude-plugins --skill api-testing -a claude-code, the skill will be at ~/.claude/skills/api-testing/SKILL.md.

What does the api-testing skill do?

Gives the agent expertise in writing HTTP API tests with Supertest (TypeScript) and httpx/pytest (Python). Covers request validation, responses, authentication, and error handling.

What dependencies does api-testing need?

For TypeScript, install supertest and @types/supertest packages (npm install -D or bun add -d). For Python, install httpx and pytest-asyncio (pip install or uv add --dev).

Source text

SKILL.md · MIT
---
created: 2025-12-16
modified: 2026-07-05
reviewed: 2026-04-25
name: api-testing
description: HTTP API testing with Supertest (TS) and httpx/pytest (Python). Use when the user mentions API testing, Supertest, httpx, REST/GraphQL validation, or HTTP response errors.
user-invocable: false
allowed-tools: Bash(curl *), Bash(http *), Bash(jq *), Read, Edit, Write, Grep, Glob, TodoWrite
---

# API Testing

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

## When to Use This Skill

| Use this skill when... | Use `configure-plugin:configure-api-tests` instead when... |
|---|---|
| Writing Supertest endpoint tests against an Express/Fastify app | Setting up Pact consumer/provider contract testing infrastructure |
| Writing httpx + pytest tests for a Python REST/GraphQL API | Validating an OpenAPI specification or wiring schema (Zod/AJV) checks into CI |
| Validating request/response shapes, status codes, and auth flows in test code | Auditing or scaffolding API contract testing tooling for a project |
| Asserting error handling (4xx/5xx) and integration state in functional tests | Adding breaking-change detection workflows to CI |

## Core Expertise

**API Testing Capabilities**
- **Request testing**: Headers, query params, request bodies
- **Response validation**: Status codes, headers, JSON schemas
- **Authentication**: Bearer tokens, cookies, OAuth flows
- **Error handling**: 4xx/5xx responses, validation errors
- **Integration**: Database state, external services
- **Performance**: Response times, load testing basics

## TypeScript/JavaScript (Supertest)

### Installation

```bash
# Using Bun
bun add -d supertest @types/supertest

# Using npm
npm install -D supertest @types/supertest
```

### Basic Setup with Express

```typescript
// app.ts
import express from 'express'

export const app = express()
app.use(express.json())

app.get('/api/health', (req, res) => {
  res.json({ status: 'ok' })
})

app.post('/api/users', (req, res) => {
  const { name, email } = req.body
  if (!name || !email) {
    return res.status(400).json({ error: 'Missing required fields' })
  }
  res.status(201).json({ id: 1, name, email })
})
```

```typescript
// app.test.ts
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: '[email protected]' })
      .expect(201)

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

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

    expect(response.body.error).toBeDefined()
  })
})
```

### Request Methods

```typescript
import request from 'supertest'
import { app } from './app'

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

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

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

// PATCH request
await request(app).patch('/api/users/1')
  .send({ email: '[email protected]' }).expect(200)

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

### Headers and Query Parameters

```typescript
// Set headers
await request(app)
  .get('/api/protected')
  .set('Authorization', 'Bearer token123')
  .set('Content-Type', 'application/json')
  .expect(200)

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

### Response Assertions

```typescript
describe('Response validation', () => {
  it('validates status code', async () => {
    await request(app).get('/api/users').expect(200)
  })

  it('validates headers', async () => {
    await request(app).get('/api/users')
      .expect('Content-Type', /json/).expect(200)
  })

  it('validates response body', async () => {
    const response = await request(app).get('/api/users/1').expect(200)
    expect(response.body).toEqual({
      id: 1,
      name: 'John Doe',
      email: '[email protected]',
      createdAt: expect.any(String),
    })
  })

  it('validates array responses', async () => {
    const response = await request(app).get('/api/users').expect(200)
    expect(response.body).toBeInstanceOf(Array)
    expect(response.body).toHaveLength(5)
    expect(response.body[0]).toHaveProperty('id')
  })
})
```

## Python (httpx + pytest)

### Installation

```bash
# Using uv
uv add --dev httpx pytest-asyncio

# Using pip
pip install httpx pytest-asyncio
```

### Basic Setup with FastAPI

```python
# main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    name: str
    email: str

@app.get("/api/health")
def health_check():
    return {"status": "ok"}

@app.post("/api/users", status_code=201)
def create_user(user: User):
    return {"id": 1, "name": user.name, "email": user.email}

@app.get("/api/users/{user_id}")
def get_user(user_id: int):
    if user_id == 999:
        raise HTTPException(status_code=404, detail="User not found")
    return {"id": user_id, "name": "John Doe", "email": "[email protected]"}
```

```python
# test_main.py
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": "[email protected]"}
    )
    assert response.status_code == 201
    data = response.json()
    assert data["name"] == "John Doe"
    assert "id" in data

def test_validation_error():
    response = client.post("/api/users", json={"name": "John"})
    assert response.status_code == 422  # FastAPI validation error

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

For detailed examples including authentication testing, file uploads, cookie testing, database integration, schema validation, GraphQL testing, performance testing, best practices, and troubleshooting, see [REFERENCE.md](REFERENCE.md).

## Agentic Optimizations

| Context | Command |
|---------|---------|
| Quick test (Bun) | `bun test --dots --bail=1 api` |
| Quick test (pytest) | `pytest -x --tb=short tests/api/` |
| Run single test file | `bun test --dots path/to/test.ts` |
| Verbose on failure | `bun test --bail=1 api` |

## See Also

- `vitest-testing` - Unit testing framework
- `python-testing` - Python pytest patterns
- `playwright-testing` - E2E API testing
- `test-quality-analysis` - Test quality patterns

## References

- Supertest: https://github.com/ladjs/supertest
- httpx: https://www.python-httpx.org/
- FastAPI Testing: https://fastapi.tiangolo.com/tutorial/testing/
- Node.js Testing Best Practices: https://github.com/goldbergyoni/nodejs-testing-best-practices

© laurigates · MIT · laurigates/claude-plugins

Similar skills

All skills for Testing and QA →

api-testing by other authors comes first.

api-testing kindlmann The api-testing Claude Code skill helps write REST and GraphQL API tests. It comes into play for schema, auth, error, and pagination checks. CX Codex +1 1,800installs api-testing secondsky api-testing — a skill that gets your agent writing HTTP API tests: Supertest for TypeScript, httpx and pytest for Python. Covers REST, GraphQL and error handling. CX Codex +1 921installs api-testing fugazi api-testing is a Claude Code skill for standalone tests of REST and GraphQL contracts. It checks schemas, authentication, errors, pagination, and other API behavior without browser-driven flows. CX Codex +1 112installs api-testing oakoss api-testing is a Claude Code skill for writing REST API integration tests and checking endpoint responses. It activates for HTTP mocking, response validation, and API error tests. CX Codex +1 149installs api-test-suite-builder Alireza Rezvani api-test-suite-builder is a Claude Code skill that scans API routes and creates tests for them. Ask it to build REST endpoint checks, an integration suite, or contract tests. CX Codex +1 660installs python-testing-strategies c0x12c python-testing-strategies — a skill that tells your coding agent how to test FastAPI apps: pytest-asyncio, httpx AsyncClient, data factories and the checks every endpoint needs. CX Codex +1 ★ 111repo stars api-security-testing davila7 api-security-testing is a Claude Code skill for reviewing REST and GraphQL API security. It covers authentication, access control, input handling, rate limits, and error responses. CX Codex +1 121installs api-test-suite-generator patricio0312rev api-test-suite-generator scans your route definitions and generates API test suites with Jest, Vitest or Supertest. Useful when the endpoints exist but the tests do not. CX Codex +1 319installs api-testing-patterns proffesor-for-testing api-testing-patterns — a skill with ready-made patterns for testing REST and GraphQL APIs: contracts, auth, idempotency, race conditions. Useful when writing tests or picking a strategy. CX Codex +1 618installs superpowers-python-automation anthonylee991 superpowers-python-automation guides your agent to write dependable Python REST API integrations with timeouts, retries, pagination, and tests. It helps when building sync jobs or external service clients. CX Codex +1 1installs

From the same set27

The whole set →
git-commit-workflow The git-commit-workflow Claude Code skill defines commit-message and staging rules. It helps split related edits into focused commits and review staged changes. CX Codex +1 161installs binary-analysis binary-analysis guides your coding agent in inspecting unknown binaries, running hex dumps, and extracting embedded artifacts. CX Codex +1 146installs shell-expert shell-expert is a Claude Code skill for writing Bash, zsh, and POSIX scripts and composing command-line automation. It activates for shell pipelines and portable scripting tasks. CX Codex +1 141installs rust-development A Rust development skill covering Cargo, ownership, async code, and Tokio. It fits coding tasks that mention Rust or its core tooling. CX Codex +1 108installs clippy-advanced clippy-advanced guides Clippy setup for Rust projects: custom lints, clippy.toml thresholds, suppression rules, and CI check commands. CX Codex +1 107installs playwright-testing The playwright-testing skill guides Playwright E2E work for web apps, including browser coverage, mobile viewports, API checks, and visual snapshots. CX Codex +1 106installs cargo-nextest This Claude Code skill runs and filters Rust tests with cargo-nextest. It comes into play for test runs, CI setup, and investigations into slow or flaky tests. CX Codex +1 101installs bevy-game-engine bevy-game-engine guides AI coding assistants through building Rust games with Bevy, covering ECS setup, rendering, input, and assets. CX Codex +1 3installs

Project sponsors

Companies that keep this analytics open