rest-api-testing

graysurf's avatarfrom graysurf

Test REST APIs with repeatable, file-based requests under <project>/setup/rest, with per-project endpoint and Bearer token presets, using the bundled rest.sh (curl + jq). Use when the user asks to manually call REST endpoints, replay requests reliably, add CI-friendly assertions, and record API test reports.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 11, 2026
[Testing and QA]

When & Why to Use This Skill

This Claude skill facilitates robust REST API testing through repeatable, file-based requests. It integrates environment-specific presets, Bearer token management, and CI-friendly assertions using curl and jq, allowing developers to reliably replay requests, validate responses, and generate comprehensive markdown test reports.

Use Cases

  • Automated API Regression: Define request templates with embedded 'expect' assertions to verify endpoint stability and prevent regressions during development.
  • Multi-Environment Debugging: Seamlessly switch between local, staging, and production configurations using predefined endpoint and token presets to troubleshoot issues.
  • CI/CD Pipeline Validation: Execute automated API tests within continuous integration workflows to generate audit-ready markdown reports and ensure deployment quality.
  • Standardized Team Workflows: Maintain a version-controlled repository of API request files to ensure consistent testing procedures and easy reproduction of bugs across the team.
namerest-api-testing
descriptionTest REST APIs with repeatable, file-based requests under <project>/setup/rest, with per-project endpoint and Bearer token presets, using the bundled rest.sh (curl + jq). Use when the user asks to manually call REST endpoints, replay requests reliably, add CI-friendly assertions, and record API test reports.

REST API Testing

Contract

Prereqs:

  • bash and curl available on PATH (jq recommended for pretty-printing/assertions).
  • setup/rest/ exists (or bootstrap from template) with requests and optional endpoint/token presets.

Inputs:

  • Request file path: setup/rest/requests/<name>.request.json.
  • Optional flags/env: --env, --url, --token, --config-dir, --no-history (plus REST_URL, ACCESS_TOKEN).

Outputs:

  • Response JSON (or raw response) printed to stdout; errors printed to stderr.
  • Optional history file under setup/rest/.rest_history (gitignored; disabled via --no-history).
  • Optional markdown report via scripts/rest-report.sh.

Exit codes:

  • 0: request completed successfully (and assertions, if present, passed)
  • non-zero: invalid inputs/missing files/http error/assertion failure

Failure modes:

  • Missing curl, invalid request JSON, or missing endpoint configuration (REST_URL / endpoints env).
  • Auth missing/invalid (ACCESS_TOKEN / token profile) causing 401/403.
  • Network/timeout/connection failures.

Goal

Make REST API calls reproducible and CI-friendly via:

  • setup/rest/requests/*.request.json (request + optional expect assertions)
  • setup/rest/endpoints.env (+ optional endpoints.local.env)
  • setup/rest/tokens.env (+ optional tokens.local.env)
  • setup/rest/prompt.md (optional, committed; project context for LLMs)

TL;DR (fast paths)

Call an existing request (JSON only):

$AGENT_KIT_HOME/skills/rest-api-testing/scripts/rest.sh \
  --env local \
  setup/rest/requests/<request>.request.json \
| jq .

If the endpoint requires auth, pass a token profile (from setup/rest/tokens.local.env) or use ACCESS_TOKEN:

# Token profile (requires REST_TOKEN_<NAME> to be non-empty in setup/rest/tokens.local.env)
$AGENT_KIT_HOME/skills/rest-api-testing/scripts/rest.sh --env local --token default setup/rest/requests/<request>.request.json | jq .

# Or: one-off token (useful for CI)
REST_URL="https://<host>" ACCESS_TOKEN="<token>" \
  $AGENT_KIT_HOME/skills/rest-api-testing/scripts/rest.sh --url "$REST_URL" setup/rest/requests/<request>.request.json | jq .

Replay the last run (history):

$AGENT_KIT_HOME/skills/rest-api-testing/scripts/rest-history.sh --command-only

Generate a report (includes a replayable ## Command by default):

$AGENT_KIT_HOME/skills/rest-api-testing/scripts/rest-report.sh \
  --case "<test case name>" \
  --request setup/rest/requests/<request>.request.json \
  --env local \
  --run

Flow (decision tree)

  • If setup/rest/prompt.md exists → read it first for project-specific context.
  • No setup/rest/ yet → bootstrap from template:
    • cp -R "$AGENT_KIT_HOME/skills/rest-api-testing/template/setup/rest" setup/
  • Have request file → run with rest.sh.
  • Need a markdown report → use rest-report.sh --run (or --response).

Notes (defaults)

  • History is on by default: setup/rest/.rest_history (gitignored); one-off disable with --no-history (or REST_HISTORY=0).
  • Requests can embed CI-friendly assertions:
    • expect.status (integer; required when expect is present)
    • expect.jq (optional; evaluated with jq -e against the JSON response)
  • Reports redact common secret-like fields by default (e.g. Authorization, Cookie, accessToken); use --no-redact only when necessary.
  • Prefer --config-dir setup/rest in automation for deterministic discovery.

References

  • Full guide (project template): skills/rest-api-testing/references/REST_API_TESTING_GUIDE.md
  • Report template: docs/templates/REST_API_TEST_OUTPUT_TEMPLATE.md
  • Progress plan: docs/progress/20260108_rest-api-testing-skill.md