api-test

name

api-test

description

This skill should be used when the user wants to test an API, analyze an API spec, generate API test plans, run automated API tests, or check for security vulnerabilities. Trigger when the user says "test my API", "analyze this spec", "run API tests", "generate test code for my API", "check my OpenAPI file", "test my Postman collection", or provides an OpenAPI/Swagger/Postman/GraphQL spec file or URL. Also trigger when the user mentions Schemathesis, contract testing, or wants to validate their REST API.

API Testing

Analyzes API specs (OpenAPI, Postman, GraphQL), generates test plans, executes tests via Schemathesis, generates pytest code, and produces scored reports with actionable findings.

Scripts are in .claude/skills/api-test/scripts/. Run via:

python .claude/skills/api-test/scripts/<script>.py --help

Workspace

All output goes into .opentest-workspace/api/ in the current working directory. Create it before starting:

mkdir -p .opentest-workspace/api

Add to .gitignore if not already there:

.opentest-workspace/

Output	Path
Spec summary	.opentest-workspace/api/spec_summary.json
Test plan	.opentest-workspace/api/test_plan.json
Test results	.opentest-workspace/api/results.json

Workflow

Start by running analyze_spec.py on the provided spec file or URL. This parses the spec and returns endpoints, detected patterns (CRUD, pagination, soft-delete), auth type, and warnings.

python .claude/skills/api-test/scripts/analyze_spec.py \
  --spec path/to/openapi.yaml \
  --base-url https://api.example.com \
  --output .opentest-workspace/api/spec_summary.json

Summarize the analysis to the user: number of endpoints, patterns detected, auth type, any spec warnings.

Explore the spec for domain context. Read the spec file directly — not just the parsed summary. Look for:

• info.description — overall product context
• Per-endpoint summary and description — business rules, constraints, side effects
• Parameter descriptions — valid ranges, enums, interdependencies
• x- extensions and examples — implementation hints

From this, derive spec-driven test cases that go beyond the generic rules. Examples:

What you read in the spec	Test cases to derive
"Transfers funds between accounts"	Insufficient balance, same source/dest account, zero/negative amount, currency mismatch
"Cancels an order; only allowed if status is pending"	Cancel a shipped order → expect 4xx; cancel already-cancelled order
"Returns items sorted by created_at desc by default"	Verify sort order in response; test sort param with invalid value
enum: [active, inactive, archived] on a field	Test each valid value; test an unlisted value → expect 400/422
"Max 5 tags per item"	Submit 6 tags → expect 4xx; submit exactly 5 → expect success
Required mutual dependency ("if X then Y is required")	Provide X without Y → expect 400

Document these as additional test cases in the plan alongside the rules-based ones. Clearly label them as source: spec vs source: rule so findings are traceable.

Ask what they want next:

• (A) Run tests now and get a report
• (B) Generate pytest code for CI/CD
• (C) Both

Generate a test plan with generate_plan.py before executing or generating code:

python .claude/skills/api-test/scripts/generate_plan.py \
  --spec-summary .opentest-workspace/api/spec_summary.json \
  --focus all \
  --output .opentest-workspace/api/test_plan.json

Run tests with run_tests.py — prefer this over manual HTTP calls:

python .claude/skills/api-test/scripts/run_tests.py \
  --spec path/to/openapi.yaml \
  --base-url https://api.example.com \
  --auth '{"type": "bearer", "token": "..."}' \
  --output .opentest-workspace/api/results.json

Generate pytest code with generate_code.py:

python .claude/skills/api-test/scripts/generate_code.py \
  --plan .opentest-workspace/api/test_plan.json \
  --output-dir tests/api/

Analyze results with analyze_results.py after any test run:

python .claude/skills/api-test/scripts/analyze_results.py \
  --results .opentest-workspace/api/results.json

Reporting

Lead with the score and grade: Score: 72/100 (C). Group findings by severity, critical first. For each critical/high finding, explain the business impact — not just the technical detail.

Score	Grade	Meaning
90–100	A	Excellent — production-ready
80–89	B	Good — minor issues
70–79	C	Acceptable — several improvements needed
60–69	D	Poor — significant gaps
0–59	F	Critical — do not ship

End every report with "Top 3 things to fix" as concrete action items. Offer to generate pytest code for CI/CD.

Auth Config

Pass as JSON string to --auth:

// Bearer token
{"type": "bearer", "token": "eyJhbGciOiJIUzI1NiJ9..."}

// API Key header
{"type": "api_key", "header": "X-API-Key", "value": "key123"}

// Basic auth
{"type": "basic", "username": "user", "password": "pass"}

// OAuth2 Client Credentials
{"type": "oauth2_cc", "token_url": "https://auth.example.com/token",
 "client_id": "id", "client_secret": "secret"}

Detected Patterns → Test Strategy

When spec_summary.detected_patterns contains:

• crud_resource → run CRUD lifecycle test (create → read → update → delete)
• pagination → test empty page, large page_size, page out of bounds
• soft_delete → verify resource still appears in GET after DELETE
• post_create → assert 201 status + Location header present