Skip to main content
skill CX Codex

api-testing · oakoss — Claude Code skill: API tests and installation

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.

MIT 149 installs ★ 29 updated 2026-08-17

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

What api-testing does

api-testing lays out ways to test HTTP endpoints with Supertest, MSW, and Vitest. It covers status, header, and body assertions, Zod schema checks, test organization, and error cases. MSW v2 intercepts outgoing requests, while Supertest sends requests to Express, Fastify, and Hono apps without starting a separate server.

For Fastify, pass fastify.server to Supertest; Fastify also offers its own app.inject() method. The skill covers MSW handler setup and resetting handlers between tests. For pure functions it points to direct assertions; browser end-to-end and load tests call for other tools, such as Playwright or Cypress, and k6 or Artillery.

What it helps with

  • assert REST endpoint status codes and response bodies
  • mock a failed external HTTP request with MSW
  • validate response headers and schemas
  • organize tests for Express, Fastify, or Hono

Example prompts for the agent

  • Write Express REST API integration tests that check status codes and response bodies.
  • Mock an external API request with MSW and test the network failure case.
  • Add a Zod response schema check for this Fastify endpoint.

How to install api-testing

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --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 do I install api-testing in Claude Code?

Run npx skills add oakoss/agent-skills --skill api-testing -a claude-code. The skill file is at ~/.claude/skills/api-testing/SKILL.md.

What does api-testing do?

It guides REST API tests, including request setup, response assertions, and HTTP interception with MSW. It also covers schema checks and test organization.

How does api-testing handle Fastify differently from Express?

For Fastify, use app.inject() or give Supertest fastify.server. Supertest can use an Express app directly.

Source text

SKILL.md · MIT
---
name: api-testing
description: |
  API testing patterns with supertest, MSW, and Vitest. Covers integration testing for REST APIs, HTTP request mocking with Mock Service Worker v2, response assertions, schema validation, test organization, and framework-specific patterns for Express, Fastify, and Hono.

  Use when writing integration tests for REST APIs, mocking HTTP requests, or testing API endpoints. Use for api-test, supertest, msw, mock-service-worker, integration-test, http-mock, endpoint-test, request-test.
license: MIT
metadata:
  author: oakoss
  version: '1.0'
  source: 'https://mswjs.io/docs'
user-invocable: false
---

# API Testing

## Overview

API testing validates HTTP endpoints by sending requests and asserting responses, covering status codes, headers, body content, and error handling. Supertest provides a fluent chainable API for integration testing against Express, Fastify, and Hono apps without starting a real server. MSW (Mock Service Worker) v2 intercepts outgoing HTTP requests at the network level, enabling realistic mocking of external services in both Node.js tests and browser environments.

**When to use:** Integration tests for REST APIs, testing middleware pipelines, validating request/response contracts, mocking third-party APIs in tests, testing error handling and edge cases.

**When NOT to use:** Unit testing pure functions (use direct assertions), E2E browser testing (use Playwright/Cypress), load/performance testing (use k6/Artillery), testing static file serving.

## Quick Reference

| Pattern               | API                                        | Key Points                                  |
| --------------------- | ------------------------------------------ | ------------------------------------------- |
| GET request           | `request(app).get('/path')`                | Returns supertest `Test` object             |
| POST with body        | `request(app).post('/path').send(body)`    | Automatically sets Content-Type             |
| Auth header           | `.set('Authorization', 'Bearer token')`    | Chain before `.expect()`                    |
| Status assertion      | `.expect(200)`                             | Chainable with body assertions              |
| Body assertion        | `.expect({ key: 'value' })`                | Deep equality check                         |
| Header assertion      | `.expect('Content-Type', /json/)`          | Accepts string or regex                     |
| MSW HTTP handler      | `http.get('/api/users', resolver)`         | Intercepts matching requests                |
| MSW GraphQL handler   | `graphql.query('GetUser', resolver)`       | Intercepts by operation name                |
| MSW response          | `HttpResponse.json(data, { status })`      | v2 response format                          |
| MSW error simulation  | `HttpResponse.error()`                     | Simulates network failure                   |
| MSW one-time handler  | `http.get(path, resolver, { once: true })` | Auto-removed after first match              |
| MSW per-test override | `server.use(handler)`                      | Override default handlers in specific tests |
| Schema validation     | `schema.parse(response.body)`              | Validates response structure with Zod       |
| Cookie persistence    | `const agent = request.agent(app)`         | Maintains cookies across requests           |
| Fastify inject        | `app.inject({ method, url })`              | Built-in testing without supertest          |
| Hono test client      | `testClient(app)`                          | Type-safe request builder                   |

## Common Mistakes

| Mistake                                    | Correct Pattern                                             |
| ------------------------------------------ | ----------------------------------------------------------- |
| Not awaiting supertest requests            | Always `await request(app).get('/path')`                    |
| Sharing server state between tests         | Reset handlers with `server.resetHandlers()` in `afterEach` |
| Mocking fetch/axios directly               | Use MSW to intercept at the network level                   |
| Forgetting `server.listen()` in setup      | Call in `beforeAll`, `resetHandlers` in `afterEach`         |
| Passing Fastify instance to supertest      | Use `fastify.server` (the underlying Node server)           |
| Asserting before response completes        | Use `await` or return the supertest chain                   |
| Hardcoding test data across many tests     | Use factories or fixtures for test data                     |
| Not testing error responses                | Test 4xx and 5xx paths alongside happy paths                |
| Using `server.close()` in `afterEach`      | Use `afterAll` for close, `afterEach` for reset only        |
| Ignoring response headers in assertions    | Validate Content-Type, Cache-Control, CORS headers          |
| Not using `onUnhandledRequest: 'error'`    | Catch unhandled requests to prevent silent test gaps        |
| Testing implementation instead of behavior | Assert on response shape, not internal function calls       |

## Delegation

- **Test structure review**: Use `Task` agent
- **Code review**: Delegate to `code-reviewer` agent
- **Pattern discovery**: Use `Explore` agent

> If the `vitest-testing` skill is available, delegate general Vitest configuration and patterns to it.
> Otherwise, recommend: `npx skills add oakoss/agent-skills --skill vitest-testing`

## References

- [Supertest integration testing patterns for Express, Fastify, and Hono](references/supertest-patterns.md)
- [MSW request handlers, response resolvers, and server setup](references/msw-handlers.md)
- [Test organization, fixtures, factories, and setup/teardown](references/test-organization.md)
- [Response assertions, status codes, headers, and schema validation](references/assertion-patterns.md)

© oakoss · MIT · oakoss/agent-skills

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 laurigates 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. CX Codex +1 106installs playwright-api-testing-cursorrules-prompt-file PatrickJS playwright-api-testing-cursorrules-prompt-file configures Cursor to generate Playwright API tests using pw-api-plugin. It helps test status codes and validate response schemas with Zod. CX Codex +1 ★ 41,178repo stars integration-testing aj-geddes integration-testing helps design and implement integration tests for APIs, databases, message queues, and external services. Useful for validating end-to-end interactions between system components. CX Codex +1 564installs jest-testing pluginagentmarketplace This skill guides Jest testing for Node.js, from unit checks to API tests with Supertest. Use it when you need examples for mocks, coverage reports, or CI runs. CX Codex +1 121installs sveltekit-restful-api-tailwind-css-cursorrules-pro PatrickJS The sveltekit-restful-api-tailwind-css-cursorrules-pro rule gives Cursor project guidance for SvelteKit, REST APIs, Tailwind CSS, testing, and file management. Use it to keep those practices in view while working on a project. CX Codex +1 ★ 41,178repo stars 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 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

From the same set106

The whole set →
changesets The changesets skill manages package versions and changelogs in a monorepo. Use it to coordinate releases and publish packages to npm. CX Codex +1 154installs opentofu Get help writing and reviewing OpenTofu configurations and Pulumi programs. Use the skill to manage infrastructure code, state, and environment setups. CX Codex +1 153installs arktype-validation arktype-validation — a skill for ArkType, where schemas are TypeScript-shaped strings. Covers morphs, scopes and ArkEnv checks for environment variables. Handy for runtime validation that stays close to the type syntax. CX Codex +1 153installs tanstack-router tanstack-router adds guidance for type-safe file-based React routing with @tanstack/react-router. Useful for loaders, search param validation, and code splitting. CX Codex +1 150installs github-actions Create and configure GitHub Actions workflows, from event triggers and build matrices to caching and authentication. Useful for automating tests, releases, and deployments. CX Codex +1 149installs git-workflow git-workflow guides AI coding agents through trunk-based development, conventional commits, reusable GitHub Actions workflows, and Git history repair. CX Codex +1 149installs ux-designer ux-designer is a Claude Code skill that guides AI agents from information architecture to developer handoff, with usability and accessibility checks. CX Codex +1 148installs responsive-images Implements performant responsive images with srcset, modern formats like AVIF and WebP, CLS prevention, and LCP prioritization. CX Codex +1 148installs

Project sponsors

Companies that keep this analytics open