HTTP API Test Runner

Use this skill to turn one-off HTTP checks into reusable .http cases and a runnable verification script.

Prerequisites

Required runtime dependencies:

• bash
• curl
• python3

Quick self-check:

bash --version
curl --version
python3 --version

Generate two artifacts by default:

• .api-tests.http
• .api-verify.sh

The .http file is the source of truth. The shell script executes the cases, prints readable PASS/FAIL/SKIP output, and exits non-zero when any non-skipped case fails.

Quick Start

1. Collect only the missing inputs: host, method, auth, request data, cases, and expected results.
2. Choose a starting point:
• Use templates/ for a new endpoint.
• Use examples/ when the endpoint looks similar to an existing example.
• Use references/complex-scenarios.md for multi-step or advanced validation.
3. Generate or update:
• .api-tests.http
• .api-verify.sh
4. Validate the generated script:

bash -n './<feature>.api-verify.sh'
bash './<feature>.api-verify.sh'
COOKIE='full Cookie header' AUTH_TOKEN='token value' bash './<feature>.api-verify.sh'
# optional for unstable networks:
MAX_TIME=40 RETRY_COUNT=2 RETRY_DELAY=1 bash './<feature>.api-verify.sh'

1. If cases fail, classify the problem before editing assertions:
• auth mismatch
• request shape mismatch
• environment or fixture mismatch
• business assertion mismatch

See references/debugging-cookbook.md for the failure checklist.

Need a minimal runnable path first: see GET_STARTED.md.

What To Collect

Ask only for fields the user did not already provide.

For cookie-based tests, tell the user to copy the full Cookie: request header from a successful browser Network request. Do not reconstruct cookies from the storage panel.

Generated comments and final usage notes should follow the user's language.

Choose Your Starting Point

• templates/basic.api-tests.txt
• Fastest path for a new endpoint.
• Includes a small set of common variables and assertions.
• templates/basic.api-verify.sh
• Runnable shell script with timeout handling, env-based secrets, and formatted output.
• examples/resource-detail/
• Resource detail lookup with cookie auth and JSON field assertions.
• examples/auth-login-required/
• Unauthenticated and invalid-auth cases.
• examples/list-assertions/
• List projection, membership, and absence checks.
• examples/async-job-polling/
• Submit -> poll -> verify pattern with a runnable pre-step script for async workflows.

Note: publishable skill assets use .api-tests.txt to satisfy upload restrictions, while generated runtime artifacts should still use .api-tests.http.

Scenario Index

Artifact Contract

The generated .http file should:

• declare variables such as @host, @cookie, @token, @resourceId
• use ### titles for each case
• keep one request per case
• add explicit expect.* comments
• keep real secrets out of the file by default

The generated shell script should:

• read the .http file
• resolve {{variable}} placeholders
• accept secrets from environment variables
• print PASS/FAIL/SKIP output for each case
• print a summary line
• exit non-zero if any non-skipped case fails

Safety Rules

• Do not commit real cookies, tokens, passwords, or internal credentials.
• Use placeholders such as @cookie = and @token = .
• When secrets are missing, authenticated cases should SKIP with a clear reason instead of crashing the parser.
• Before publishing or committing generated artifacts, run a lightweight secret scan:

rg -n "password|secret|session_id|auth_token|access_token|refresh_token" <artifact-dir>
rg -n "Authorization: Bearer [A-Za-z0-9._-]+|C[o]okie: [A-Za-z0-9_%-]+=" <artifact-dir>

Reference Map

• Fastest first run: GET_STARTED.md
• Assertion reference: references/assertion-cheatsheet.md
• Complex flows and advanced validation: references/complex-scenarios.md
• Failure diagnosis and triage: references/debugging-cookbook.md
• FAQ: references/faq.md
• Lightweight publishable example: references/http_test_artifact_example.md

Default Running Checks

After generating artifacts, run:

bash -n './<feature>.api-verify.sh'
bash './<feature>.api-verify.sh'
COOKIE='full Cookie header' AUTH_TOKEN='token value' bash './<feature>.api-verify.sh'

Interpretation:

• bash -n catches shell syntax errors.
• Running without secrets should verify parsing and expected SKIP behavior.
• Running with secrets should verify actual API behavior and assertions.