HTTP API Test Runner

Turn one-off HTTP checks into reusable .http cases and a runnable verification script. use this skill when the user wants to create .http files, run HTTP/REST API checks, replay browser or curl requests, validate JSON fields or response markers, compare expected vs actual responses, or generate formatted PASS/FAIL API test reports.

Intent

Generate two production artifacts (a .http file and a shell verification script) that codify HTTP API test cases with explicit authentication, request payloads, and validation rules. the .http file becomes the source of truth. the script executes cases, prints readable PASS/FAIL/SKIP output per case, and exits non-zero if any non-skipped case fails. use this when you need repeatable API test coverage that doesn't require a full test framework, or when you want to version-control API contracts alongside your codebase.

Inputs

external connections:

• http endpoint (no setup required, provided by user)
• optional: credential store or vault (not automated; user must inject via env var before running script)

Procedure

1. collect inputs from the user. ask only for fields not already provided. use the table above as a checklist. if a field is unclear, ask for a concrete example (real or sanitized).

2. choose a starting point:

   • use templates/basic.api-tests.http.txt for a new endpoint. includes common variables and assertions.
   • use templates/basic.api-verify.sh as the shell script template. includes timeout handling, env-based secrets, formatted output.
   • reference examples/resource-detail/ if the endpoint looks like a resource lookup with JSON field assertions.
   • reference examples/auth-login-required/ if you need unauthenticated and invalid-auth cases.
   • reference examples/list-assertions/ if validation involves list projection or membership checks.
   • reference examples/async-job-polling/ if the flow is submit then poll then verify.
   • reference references/complex-scenarios.md for multi-step or advanced validation patterns.

   input for this step: user description, any code snippet, curl command, browser network tab export, or endpoint documentation. output for this step: choice of template + rationale noted in comments.

3. generate the .http file (<feature>.api-tests.http) with:

   • declared variables at the top (e.g., @host, @cookie, @token, @resourceId). use <set via COOKIE> placeholders for secrets.
   • one ### title per case (e.g., ### login with valid credentials).
   • one request per case. include method, path, query string, headers, and body as needed.
   • explicit expect.* comments before each request (e.g., // expect status 200, data.user.email in response).
   • no real secrets committed to the file by default.

   input for this step: collected user inputs (base URL, method, auth, cases, assertions). output for this step: .http file text, ready to save.

4. generate the shell script (<feature>.api-verify.sh) with:

   • shebang: #!/bin/bash.
   • read the .http file line by line.
   • resolve {{variable}} placeholders from shell variables or env vars.
   • accept secrets from environment variables (e.g., COOKIE, AUTH_TOKEN, API_KEY). if a secret is missing and a case requires it, mark the case as SKIP.
   • execute each case via curl or http CLI. capture status code and response body.
   • print PASS, FAIL, or SKIP for each case with a short reason.
   • print a summary line (e.g., 5 passed, 1 failed, 1 skipped).
   • exit with code 0 if all non-skipped cases passed, non-zero if any non-skipped case failed.
   • include timeout handling (e.g., --max-time 10 for curl) to prevent hanging.

   input for this step: .http file text, validation rules. output for this step: shell script text, ready to save and execute.

5. validate the generated script by running:

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

   • bash -n catches syntax errors.
   • running without secrets verifies parsing and expected SKIP behavior.
   • running with secrets verifies actual API behavior and assertions.

   input for this step: generated script, curl or http client on user's system. output for this step: validation report (syntax pass/fail, case results, summary).

6. if cases fail, classify the problem before editing assertions:

   • auth mismatch (token expired, invalid scope, wrong header format).
   • request shape mismatch (wrong method, path params, query string, body structure).
   • environment or fixture mismatch (base URL wrong, test data missing, dependency not set up).
   • business assertion mismatch (status code or JSON path doesn't match actual response). refer to references/debugging-cookbook.md for the failure checklist.

   input for this step: test output, actual API response. output for this step: diagnosis + corrected .http file or script.

7. before publishing or committing, 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>
   

   remove or redact any real credentials found.

   input for this step: generated .http file and script. output for this step: clean artifacts, safe to commit.

Decision Points

if the user provides a curl command or browser network request: extract method, path, headers, and body. map to .http syntax. prompt for expected results and additional test cases (positive, negative, boundary).

if the user provides endpoint documentation (swagger, openapi, postman collection): parse the spec. extract method, path, params, request/response schemas. generate baseline cases. ask for custom auth and edge cases specific to their usage.

if authentication is required but no credential is provided: generate the .http file with placeholder variables (e.g., @token = <set via AUTH_TOKEN>). in the shell script, skip authenticated cases with reason: "skipped: AUTH_TOKEN not set". do not crash the parser.

if a case uses cookie-based auth: instruct the user to copy the full Cookie: request header from the browser network tab after a successful login. do not reconstruct cookies from the browser storage panel (inconsistent headers, missing attributes). assign to variable @cookie = <set via COOKIE>.

if expected results include json path assertions: use dot notation (e.g., data.user.email) or array indices (e.g., items[0].id). validate that the JSON path is valid before generating. if the path is invalid or the response is not JSON, mark the case as FAIL with reason: "response not valid JSON" or "path not found".

if a case is marked as "skip" or "todo": in the .http file, prefix the case title with SKIP:. in the shell script, skip the case and print reason: "skipped: marked as todo".

if the user wants to save raw responses for manual review: add an optional --output-dir flag to the shell script. save response bodies to <output-dir>/<case-name>.json or .txt. do not overwrite without warning.

if rate limiting or network timeouts occur during test execution: catch curl error codes (e.g., 28 for timeout, 7 for connection failed). print diagnostic message (e.g., "FAIL: timeout after 10s") and include in failure count. do not retry automatically; let the user decide.

Output Contract

.http artifact (<feature>.api-tests.http):

• plain text, valid .http dialect (IntelliJ, VS Code REST Client, or similar).
• variables declared at top with @name = value syntax. secrets use <set via ENV_VAR> placeholders.
• one ### section title per test case.
• one request per case: method, path (with {param} placeholders), query string, headers, body.
• explicit expect.* comment above each request documenting assertion intent.
• no real passwords, tokens, or internal credentials in the file.
• file location: <feature>.api-tests.http in the project root or tests/api/ directory.

shell script artifact (<feature>.api-verify.sh):

• executable bash script with shebang #!/bin/bash.
• reads the .http file and resolves placeholders from env vars.
• outputs one line per test case: [PASS/FAIL/SKIP] <case-name>: <reason>.
• outputs summary line: <N> passed, <M> failed, <K> skipped. exit code: <0 or 1>.
• exits 0 if all non-skipped cases passed, non-zero if any failed.
• file location: <feature>.api-verify.sh in the project root or tests/api/ directory.
• permissions: executable (chmod +x on unix).

validation report (if provided):

• one line per case with pass/fail status and reason.
• syntax check result (bash -n pass/fail).
• final exit code.

Outcome Signal

the skill worked when:

1. both artifacts (.http file and shell script) are generated and saved to the specified location.
2. running bash -n './<feature>.api-verify.sh' exits 0 (no syntax errors).
3. running bash './<feature>.api-verify.sh' executes all cases, prints readable output with status per case, and prints a summary line.
4. running the script with secrets injected (e.g., COOKIE='...' AUTH_TOKEN='...' bash './<feature>.api-verify.sh') produces actual test results against the API endpoint.
5. the script exits 0 when all non-skipped cases pass, and non-zero when any case fails.
6. the .http file contains no real secrets and can be safely committed.
7. all assertions match the user's intent (correct status codes, JSON paths, error messages, etc.).