Agent skill

test-endpoints

This skill automates API endpoint testing and documentation. It runs curl requests against specified endpoints, captures responses, validates against OpenAPI spec, and generates markdown documentation. Use after implementing new endpoints or when verifying API behavior.

View SKILL.md on GitHub Repository
Stars 2
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/adryanev/.dotfiles/tree/main/.claude/commands/test-endpoints

SKILL.md

  1. Single endpoint - Test one specific endpoint
  2. Multiple endpoints - Test a list of endpoints
  3. All endpoints for a resource - Test all endpoints under a path prefix
  4. Regression test - Re-test previously documented endpoints

Provide endpoint(s) or select an option.

Get from user:

  • Base URL (default: http://localhost:8080)
  • Endpoint path(s) to test
  • HTTP method(s)
  • Query parameters or request body
  • Headers (e.g., Accept-Language: id)
  • Authentication if needed

Step 2: Execute Curl Requests

For each endpoint, execute curl with full options:

bash
# GET with query params
curl -s -X GET "http://localhost:8080/api/v1/endpoint?param=value" \
  -H "Accept: application/json" \
  -H "Accept-Language: id" | jq '.'

# POST with JSON body
curl -s -X POST "http://localhost:8080/api/v1/endpoint" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"key": "value"}' | jq '.'

# GET with path parameter
curl -s -X GET "http://localhost:8080/api/v1/resource/01HGXK3V6P8QWNM0T1234ABCDE" \
  -H "Accept: application/json" | jq '.'

Step 3: Capture and Format Response

For each response, capture:

  • HTTP status code
  • Response headers
  • Response body (formatted with jq)
  • Response time
bash
# Capture with timing and status
curl -s -w "\n\nStatus: %{http_code}\nTime: %{time_total}s\n" \
  -X GET "http://localhost:8080/api/v1/endpoint" | jq '.'

Step 4: Validate Response Structure

Compare response against OpenAPI spec:

  • All required fields present
  • Field types match spec
  • Enum values are valid
  • Nested objects have correct structure

Step 5: Generate Documentation

Create markdown documentation in this format:

markdown
# API Endpoint Test Results

**Test Date:** YYYY-MM-DD HH:MM:SS
**Base URL:** http://localhost:8080
**Environment:** local/staging/production

---

## Endpoint: GET /api/v1/resource

### Request

```bash
curl -X GET "http://localhost:8080/api/v1/resource?page=1&limit=10" \
  -H "Accept: application/json" \
  -H "Accept-Language: id"

Response

Status: 200 OK Time: 0.045s

json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100
  }
}

Validation

  • Status code matches expected (200)
  • Response structure matches OpenAPI spec
  • All required fields present
  • Field types correct
</workflow>

<test_scenarios>
## Common Test Scenarios

### Pagination Testing
```bash
# First page
curl -s "http://localhost:8080/api/v1/resource?page=1&limit=10" | jq '.pagination'

# Last page
curl -s "http://localhost:8080/api/v1/resource?page=999&limit=10" | jq '.pagination'

# Invalid page
curl -s "http://localhost:8080/api/v1/resource?page=-1&limit=10" | jq '.'

Filter Testing

bash
# Single filter
curl -s "http://localhost:8080/api/v1/search?subject_type=individual" | jq '.'

# Multiple filters
curl -s "http://localhost:8080/api/v1/search?subject_type=individual&nation=indonesia" | jq '.'

# Empty filter (should return all)
curl -s "http://localhost:8080/api/v1/search" | jq '.'

Sort Testing

bash
# Sort ascending
curl -s "http://localhost:8080/api/v1/search?sort=name_asc" | jq '.data[:3]'

# Sort descending
curl -s "http://localhost:8080/api/v1/search?sort=name_desc" | jq '.data[:3]'

i18n Testing

bash
# Indonesian
curl -s "http://localhost:8080/api/v1/resource" -H "Accept-Language: id" | jq '.data[0]'

# English
curl -s "http://localhost:8080/api/v1/resource" -H "Accept-Language: en" | jq '.data[0]'

Error Response Testing

bash
# Invalid ID format
curl -s "http://localhost:8080/api/v1/resource/invalid-id" | jq '.'

# Not found
curl -s "http://localhost:8080/api/v1/resource/01HGXK3V6P8QWNM0T1234XXXXX" | jq '.'

# Invalid parameters
curl -s "http://localhost:8080/api/v1/search?year_range=invalid" | jq '.'

</test_scenarios>

<output_formats>

Output Format Options

1. Inline (default)

Show results directly in conversation.

2. Markdown File

Save to docs/api-tests/YYYY-MM-DD-{endpoint}.md

3. Summary Table

markdown
| Endpoint | Method | Status | Time | Valid |
|----------|--------|--------|------|-------|
| /api/v1/search | GET | 200 | 0.05s | Yes |
| /api/v1/filters | GET | 200 | 0.02s | Yes |

</output_formats>

<quick_test_commands>

Quick Test Commands

bash
# Health check
curl -s http://localhost:8080/health | jq '.'

# Beneficial ownership search
curl -s "http://localhost:8080/api/v1/beneficial-ownership/search?keyword=test&page=1&limit=10" | jq '.'

# Filters endpoint
curl -s http://localhost:8080/api/v1/beneficial-ownership/filters | jq '.'

# Chart data
curl -s http://localhost:8080/api/v1/beneficial-ownership/chart/countries | jq '.'

# Procurement search
curl -s "http://localhost:8080/api/v1/procurement/search?page=1&limit=10" | jq '.'

# LLM chatbot
curl -s -X POST "http://localhost:8080/api/v1/chatbot/message" \
  -H "Content-Type: application/json" \
  -d '{"thread_id":"test","user_message":"hello"}' | jq '.'

</quick_test_commands>

<success_criteria> Testing is complete when:

  • All specified endpoints tested
  • Response structure documented
  • Status codes verified
  • Edge cases tested (empty results, invalid params)
  • i18n variations tested (if applicable)
  • Documentation generated </success_criteria>

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

adryanev/.dotfiles

karpathy-mode

This skill should be used to enforce a disciplined coding workflow that avoids common LLM mistakes. It applies when writing code, implementing features, or when the user says /karpathy, /k-mode, or asks for "careful", "disciplined", or "minimal" implementation. Enforces assumption surfacing, simplicity-first coding, surgical changes, and test-driven execution.

2 0
Explore
adryanev/.dotfiles

disciplined-work

This skill should be used to execute work plans with strict coding discipline that avoids common LLM mistakes. It merges structured plan execution (phased workflow, incremental commits, quality checks) with disciplined coding guardrails (assumption surfacing, simplicity-first, surgical changes, test-driven execution). Triggers on /disciplined-work, /k-work, "disciplined work", or "careful work".

2 0
Explore
adryanev/.dotfiles

github-issues-from-spec

This skill transforms feature specifications, requirements documents, or plans into well-structured GitHub issues. It chunks large features into small, testable issues, creates them via gh CLI, and adds them to the appropriate GitHub project with labels. Use when converting specs to actionable issues.

2 0
Explore
adryanev/.dotfiles

new-go-endpoint

This skill automates the API-first workflow for creating new Go API endpoints. It handles OpenAPI spec updates, code generation, SQLC query creation, handler implementation, and Redis caching patterns. Use when adding new endpoints to the Lexicon backend.

2 0
Explore
mattpocock/skills

obsidian-vault

Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian.

111,310 9,758
Explore
mattpocock/skills

edit-article

Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.

111,310 9,758
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results